.NET Custom Error Pages

Setting up custom error pages in IIS for different HTTP status codes can greatly improve the user experience and provide useful information during server-side issues. Below is an example configuration for custom error pages in a .NET application.

Understanding the Need for Custom Error Pages

When a user encounters an error while interacting with your web application, the default error page provided by the server can often be cryptic and unhelpful. Custom error pages offer a more user-friendly and informative experience. By tailoring these pages to your specific needs, you can:

Improve User Experience: Provide clear and concise error messages that guide users towards a solution.
Maintain Brand Consistency: Ensure your error pages align with your website’s overall design and branding.
Enhance SEO: Optimize your error pages with relevant content and appropriate meta tags to improve search engine visibility.

Configuring Custom Error Pages in web.config

The web.config file is the primary configuration file for ASP.NET applications. To define custom error pages, you’ll need to modify the section within this file.

Here’s a concise example/structure of how you go about:

<configuration>
  ...
  <system.webServer>
    ...
    <httpErrors>
      ...
      <remove statusCode="404" subStatusCode="-1" />
      <error statusCode="404" path="~/ErrorPages/NotFound.aspx" />
    </httpErrors>
  </system.webServer>
</configuration>

A more verbose example:

<?xml version="1.0" encoding="UTF-8"?>
<configuration>
  <system.webServer>
    <httpErrors>
      <remove statusCode="502" subStatusCode="-1" />
      <remove statusCode="501" subStatusCode="-1" />
      <remove statusCode="500" subStatusCode="-1" />
      <remove statusCode="412" subStatusCode="-1" />
      <remove statusCode="406" subStatusCode="-1" />
      <remove statusCode="405" subStatusCode="-1" />
      <remove statusCode="404" subStatusCode="-1" />
      <remove statusCode="403" subStatusCode="-1" />
      <remove statusCode="401" subStatusCode="-1" />
      <remove statusCode="400" />
      <error statusCode="400" path="C:\Inetpub\example.com\error_docs\bad_request.html" />
      <remove statusCode="407" />
      <error statusCode="407" path="C:\Inetpub\example.com\error_docs\proxy_authentication_required.html" />
      <remove statusCode="414" />
      <error statusCode="414" path="C:\Inetpub\example.com\error_docs\request-uri_too_long.html" />
      <remove statusCode="415" />
      <error statusCode="415" path="C:\Inetpub\example.com\error_docs\unsupported_media_type.html" />
      <remove statusCode="503" />
      <error statusCode="503" path="C:\Inetpub\example.com\error_docs\maintenance.html" />
      <error statusCode="401" prefixLanguageFilePath="" path="C:\Inetpub\example.com\error_docs\unauthorized.html" />
      <error statusCode="403" prefixLanguageFilePath="" path="C:\Inetpub\example.com\error_docs\forbidden.html" />
      <error statusCode="404" prefixLanguageFilePath="" path="C:\Inetpub\example.com\error_docs\not_found.html" />
      <error statusCode="405" prefixLanguageFilePath="" path="C:\Inetpub\example.com\error_docs\method_not_allowed.html" />
      <error statusCode="406" prefixLanguageFilePath="" path="C:\Inetpub\example.com\error_docs\not_acceptable.html" />
      <error statusCode="412" prefixLanguageFilePath="" path="C:\Inetpub\example.com\error_docs\precondition_failed.html" />
      <error statusCode="500" prefixLanguageFilePath="" path="C:\Inetpub\example.com\error_docs\internal_server_error.html" />
      <error statusCode="501" prefixLanguageFilePath="" path="C:\Inetpub\example.com\error_docs\not_implemented.html" />
      <error statusCode="502" prefixLanguageFilePath="" path="C:\Inetpub\example.com\error_docs\bad_gateway.html" />
    </httpErrors>
  </system.webServer>
</configuration>

Example Custom Error Page (not_found.html):

<!doctype html>
<html>
  <head>
    <title>Page Not Found</title>
  </head>
  <body>
    <h1>404 Not Found</h1>
    <p>The page you requested could not be found.</p>
    <p>Please check the URL and try again.</p>
    <a href="/">Go back to the homepage</a>
  </body>
</html>

This is just an example; the page should be well designed. Especially, the 4xx error pages; these can easily be dynamic pages.