Home | Contact Us

CSharp | Java | Python | Swift | GO | WPF | Ruby | Scala | F# | JavaScript

ASP.NET customErrors Element

This ASP.NET tutorial covers the customErrors element. It creates custom 404 pages.

CustomErrors. Custom error pages are specified with customErrors.

This allows you to show visitors a link to your home page or to your sitemap. We will use the customErrors element in Web.config to gain specialized errors the easiest way.

Web.config. On the right side of Visual Studio, you will see the Web.config file icon. Open it and add the highlighted markup to your project in the appropriate location. Note that new Web.configs already have the customErrors element.

Web.config example: XML

<?xml version="1.0"?>

	<customErrors defaultRedirect="404.aspx"


Web.config enables developers to configure html error pages to be displayed in place of an error stack trace. Every new Web.config contains a comment that tells you the purpose of customErrors.

The customErrors section enables configuration of what to do if/when an unhandled error occurs during the execution of a request. Comment, Web.config

404 file. Let us make a 404 file. You can use any file as a 404 error file in the defaultRedirect attribute value, but I suggest you use a new web form file called 404.aspx, or a generic handler called 404.ashx.

First: Click on "Add Existing Item" in the Website menu and add a Web Forms page called 404.aspx.

404 file example: ASPX

<%@ Page Language="C#" %>
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"

<script runat="server">

<html xmlns="">

    <p>Sorry, the page could not be found.
    [<a href="Sitemap.aspx">Sitemap</a>]</p>


The markup can be placed in the 404.aspx file. You may want to have your site-specific text and styling applied to the page. The example has a link pointing to a Sitemap.aspx file, but you will need to manually create this in your site.

Test: Type an invalid URL into your browser, such as "Invalid.aspx". You should see the custom error ASPX file, 404.aspx.

Note: The remainder of this article talks about more specific options with customErrors and HTTP errors in general.

Attributes. We next look at MSDN for more attribute details. There are several important attributes of customErrors. Not only that, but we can look at other sites and see a new attribute added in .NET 3.5, redirectMode.

DefaultRedirect: In the attribute value, type in the absolute or relative URL of your error page. I used "404.aspx".

Mode: This is the switch that turns the custom errors on or off. RemoteOnly helps for projects still in active development.

Child Element, error: If you need specific error messages to appear, you can specify the error codes and what URLs they map to.

RedirectMode: Specifies URL rewriting, which preserves the original URL in the browser. This prevents an HTTP request.

StatusCode. In the Page_Load method in your 404 page, you can assign the status code using Response.StatusCode = 404. This allows you to modify the error code. For completeness, here are some of the most important HTTP error codes.

Status Code Definitions

403 Forbidden: The server refuses to recognize the request, even though it is a valid request. Not useful because 404 can be used instead.

404 Not Found: This status code is commonly used when the server does not wish to reveal exactly why the request has been refused.

503 Service unavailable: This occurred when I wrote a popular article. If your server is overloaded, error pages won't help the problem.

Hosts. Let us consider hosting services. Most shared server plans have a separate 404 error redirect function. You will need to specify your error page in that UI from your host as well.

However, neither setting alone may work completely, in my experience. You can use custom code in Application_Error in your Global.asax for more advanced error reporting and more features.

Tip: Depending on the scale of your project, this could be appropriate. Larger projects often have more demands.

Summary. We saw how to use the customErrors element in Web.config. This lets you specify a custom page where people can click on a link to your sitemap or home page. Usability studies show that people will immediately leave a 404 page.