ASP.NET Quickstart Tutorials

Monitoring Your Application

Tracing

Trace Logging to Page Output

Application-level Trace Logging

Accessing Trace Messages in Code

Handling Errors

Customizing Error Pages

Handling Errors Programmatically

Web Events

Events and Event Providers

Configuring Events

Creating a Custom Event

Instrumenting Your Application

Throttling Events

Back to ASP.NET Home

Handling Errors

When an error occurs on a page, ASP.NET sends information about the error to the client. Errors are divided into four categories:

Configuration errors: Occur when the syntax or structure of a Web.config file in the configuration hierarchy is incorrect.
Parser errors: Occur when the ASP.NET syntax on a page is malformed.
Compilation errors: Occur when statements in a page's target language are incorrrect.
Run-time errors: Occur during a page's execution, even though the errors could not be detected at compile time.

By default, the information shown for a run-time error is the call stack (the chains of procedure calls leading up to the exception). If debug mode is enabled, ASP.NET displays the line number in source code where the run-time error originated. Debug mode is a valuable tool for debugging your application. You can enable debug mode at the page level, using the following directive:

<%@ Page Debug="true" %>

You can also enable debug mode at the application level, using the Web.config file in the application's root directory, as shown in the following example.

Note: Running debug mode incurs a heavy performance penalty. Be sure to disable it before deploying your finished application.

The following example demonstrates the use of debug mode to show source line numbers for a run-time exception. By default, if you view this example from a remote computer, you will not see debug information. To customize this example to allow viewing from a remote computer, see the section below.

VB Debug Mode

Customizing Error Pages

Depending on the circumstances, you might want to handle application errors in different ways. For example, at development time you probably want to see the detailed error pages that ASP.NET provides to help you identify and fix problems. However, once an application is being served in a production environment, you probably do not want to display detailed errors to your customer clients. You can use ASP.NET to specify whether errors are shown to local clients, to remote clients, or to both. By default, errors are shown only to local clients (those clients on the same computer as the server). You can also specify a custom error page to redirect clients to if an error occurs.

Custom errors are enabled in the Web.config file for an application. For example:

<configuration>
     <system.web>
         <customErrors defaultRedirect="genericerror.htm" 
             mode="RemoteOnly" />
     </system.web>
</configuration>

This configuration enables local clients to see the default ASP.NET detailed error pages but redirects remote clients to a custom page, genericerror.htm. This page could be an .aspx page as well. ASP.NET passes the path of the page on which the error occurred to the error page as a QueryString argument. Note that if the execution of the error page generates an error, a blank page is sent back to the remote client.

		
<%@ Page Language="VB" Description="Error page"%>

<html>
<head>
<title>Error page</title>
</head>

<body>
<h1>Error page</h1>
Error originated on: <%=Request.QueryString("ErrorPage") %>
</body>
</html>

Note: Only files mapped to the aspnet_isapi.dll extension in IIS generate these errors. Files not served through the aspnet_isapi.dll are not processed by ASP.NET and generate IIS errors. See the IIS documentation for information about configuring IIS custom errors.

The following table describes the configuration attributes and values for the <customErrors> tag.

Attribute	Description
mode	Indicates whether custom errors are enabled, disabled, or only shown to remote computers. Values: On, Off, RemoteOnly (default).
defaultRedirect	Indicates the default URL to which a browser should be redirected if an error occurs. This attribute is optional.

The Mode attribute determines whether errors are shown to local clients, remote clients, or both. The effects of each setting are described in the following table.

Mode	Local host request	Remote host request
On	Custom error page.	Custom error page.
Off	ASP.NET error page.	ASP.NET error page.
RemoteOnly	ASP.NET error page.	Custom error page.

The following sample demonstrates how the <customErrors> configuration section is used.

VB Custom Errors

In addition to redirecting to a common page for all errors, you can also assign specific error pages to specific error status codes. The <customErrors> configuration section supports an inner <error> tag that associates HTTP status codes with custom error pages. For example:

<configuration>
  <system.web>
    <customErrors mode="RemoteOnly" defaultRedirect="/genericerror.htm">
      <error statusCode="500" redirect="/error/callsupport.htm"/>
      <error statusCode="404" redirect="/error/notfound.aspx"/>
      <error statusCode="403" redirect="/error/noaccess.aspx"/>
    </customErrors>
  </system.web>
</configuration>

The following table describes the attributes and values for the <error> tag.

Attribute	Description
StatusCode	HTTP status code of errors for which the custom error page should be used. Examples: 403 Forbidden, 404 Not Found, or 500 Internal Server Error.
Redirect	URL to which the client browser should be redirected if an error occurs.

The following example demonstrates how to use the <error> tag. Note that the example specifies an .aspx page for "File Not Found" errors so that the missing page URL passed via the QueryString can be printed.

VB Error Tag

Handling Errors Programmatically

You can also handle errors in code, at either the page level or the application level. The Page base class exposes a Page_Error method, which you can override in your pages. The method is called whenever an uncaught exception is thrown at run time.

		
<script language="C#" runat="server">

Sub Page_Error(Source As Object, E As EventArgs)
    Dim message As String = "<font face=verdana color=red>" _
        & "<h4>" & Request.Url.ToString() & "</h4>" _
        & "<pre><font color='red'>" _
        & Server.GetLastError().ToString() & "</pre>" _
        & "</font>"

    Response.Write(message)
End Sub

</script>

The following sample demonstrates the Page_Error method.

VB Page_Error Method

In addition to handling errors at the page level, you might want to handle errors at the application level. To do this, use the Application_Error event in Global.asax. This event occurs for any unhandled exception thrown within the application.

		
Sub Application_Error(sender As Object, e As EventArgs)
    '...Do something here
End Sub