<customErrors> Element

Article
10/23/2006

Provides information about custom error messages for an ASP.NET application.

<configuration>
<system.web>
<customErrors>

<customErrors defaultRedirect="url"
              mode="On|Off|RemoteOnly">
   <error statusCode="statuscode"
          redirect="url"/>
</customErrors>

Required Attribute

Attribute	Option	Description
Mode		Specifies whether custom errors are enabled, disabled, or shown only to remote clients.
	On	Specifies that custom errors are enabled. If no defaultRedirect is specified, users see a generic error.
	Off	Specifies that custom errors are disabled. This allows display of detailed errors.
	RemoteOnly	Specifies that custom errors are shown only to remote clients and ASP.NET errors are shown to the local host. This is the default.

Optional Attribute

Attribute	Description
defaultRedirect	Specifies the default URL to direct a browser to if an error occurs. When defaultRedirect is not specified, a generic error is displayed instead. The URL may be absolute (for instance, https://www.contoso.com/ErrorPage.htm) or it may be relative. A relative URL such as /ErrorPage.htm is relative to the Web.config file that specified the defaultRedirect URL, not to the Web page in which the error occurred. A URL starting with a tilde (~),such as ~/ErrorPage.htm, means that the specified URL is relative to the root path of the application.

defaultRedirect

Specifies the default URL to direct a browser to if an error occurs. When defaultRedirect is not specified, a generic error is displayed instead. The URL may be absolute (for instance, https://www.contoso.com/ErrorPage.htm) or it may be relative. A relative URL such as /ErrorPage.htm is relative to the Web.config file that specified the defaultRedirect URL, not to the Web page in which the error occurred. A URL starting with a tilde (~),such as ~/ErrorPage.htm, means that the specified URL is relative to the root path of the application.

Subtag

Subtag	Description
<error>	The error subtag can appear multiple times. Each appearance defines one custom error condition.

Remarks

The <customErrors> element does not apply to errors that occur in XML Web services.

Example

The following example specifies the error handling pages to use for an ASP.NET application.

<configuration>
   <system.web>
      <customErrors defaultRedirect="GenericError.htm"
                    mode="RemoteOnly">
         <error statusCode="500"
                redirect="InternalError.htm"/>
      </customErrors>
   </system.web>
</configuration>

Requirements

Contained Within: <system.web>

Web Platform: IIS 5.0, IIS 5.1, IIS 6.0

Configuration File: Machine.config, Web.config

Configuration Section Handler: System.Web.Configuration.CustomErrorsConfigHandler