192

What is the difference between the customErrors and httpErrors sections of the web.config file in ASP.NET MVC applications?

What are the guidelines for using each section?

1
  • 2
    IMHO - HttpError is a IIS level handling for error messages while CustomError is ASP.Net handling for errors in the web application. But would love to know more...
    – Sunny
    Mar 19, 2010 at 19:51

4 Answers 4

164

*Updated April 2016

The customErrors attribute is used when the .net code is throwing an exception (404, 403, 500 etc) and the httpErrors attribute is used when IIS itself is throwing an exception.

  • /myfakeextensionslessurl --> httpErrors 404
  • /myfakeaspsx.aspx --> customErrors 404
  • /myfakeimage.jpg --> httpErrors 404
  • /throw500.apx --> customErrors 500
  • /throw500 --> customErrors 500

There are a lot of pitfalls trying to configure this correctly. So if you are looking for a quick example, the best 2 options you have are:

Example 1: Using html pages

<system.web>
  <customErrors mode="RemoteOnly" defaultRedirect="/Error500.html" redirectMode="ResponseRewrite">
    <error statusCode="403" redirect="/Error403.html" />
    <error statusCode="404" redirect="/Error404.html" />
    <error statusCode="500" redirect="/Error500.html" />
  </customErrors>
</system.web>
<system.webServer>
  <httpErrors errorMode="DetailedLocalOnly" existingResponse="Auto">
    <remove statusCode="403" />
    <remove statusCode="404" />
    <remove statusCode="500" />
    <error statusCode="403" responseMode="File" path="Error403.html" />
    <error statusCode="404" responseMode="File" path="Error404.html" />
    <error statusCode="500" responseMode="File" path="Error500.html" />
  </httpErrors>
</system.webServer>

Example 2: using aspx pages

<system.web>
  <customErrors mode="RemoteOnly" defaultRedirect="/Error500.html" redirectMode="ResponseRewrite">
    <error statusCode="403" redirect="/Error403.aspx" />
    <error statusCode="404" redirect="/Error404.aspx" />
    <error statusCode="500" redirect="/Error500.aspx" />
  </customErrors>
</system.web>
<system.webServer>
  <httpErrors errorMode="DetailedLocalOnly" existingResponse="Auto">
    <remove statusCode="403" />
    <remove statusCode="404" />
    <remove statusCode="500" />
    <error statusCode="403" responseMode="ExecuteURL" path="Error403.aspx" />
    <error statusCode="404" responseMode="ExecuteURL" path="Error404.aspx" />
    <error statusCode="500" responseMode="ExecuteURL" path="Error500.aspx" />
  </httpErrors>
</system.webServer>

And in the aspx error pages you need to do something like this (example 404 page):

<% 
    Response.StatusCode = 404;
    Response.TrySkipIisCustomErrors = true;
 %>

Note: Using extension less urls in the customErrors section is not possible!. (without hacks)

One work around is to disable custom errors and let http errors handle the custom page. A friend has created such setup, when I find some time, I will share the code.

Background

A good custom error page will:

  1. Show the real exception when you visit the problem page locally
  2. Show a custom page when you visit the problem page remotely
  3. Will not redirect, but simply show the error page content (because of seo reasons)
  4. Will show the correct status code

So to clarify some options in our config:

  1. <customErrors mode="RemoteOnly". You can specify here: On, Off, RemoteOnly.

    • On = Always show custom error pages
    • Off = Always show the real error
    • RemoteOnly = Show the error locally, but show the custom error page remotely. So we want RemoteOnly for statement 1
  2. <customErrors redirectMode="ResponseRewrite". You can specify here: ResponseRedirect or ResponseRewrite. The ResponseRedirect mode will redirect the error page to the custom error page. For a link crawler (SEO), this will result in 302 -> 500, but you want the link crawler to get a 500 error.

  3. <httpErrors errorMode="DetailedLocalOnly". This the equivalent of the customErrors mode. Options that you have: Custom, Detailed, DetailedLocalOnly.

A good blog post which helped me a lot is: http://benfoster.io/blog/aspnet-mvc-custom-error-pages

2
  • What kind relation customErrors - httpErrors and IIS config like "Send Errors to Browser" in ASP - the Debugging Properties and "Error Pages / Edit Feature Settings", "Detailed errors". ? stackoverflow.com/questions/2640526/…
    – Kiquenet
    Oct 6, 2015 at 19:42
  • Thanks to this answer, I still have hair left Sep 13 at 1:56
88

Disclaimer: This is from my experience and not proven fact.

Both are used to define error handling for a website, but different software refers to different config elements.

customErrors are a legacy (backwards compatable) element, used by Visual Studio Development Server (aka. VSDS or Cassini).

httpErrors are the new element which is only used by IIS7.

This highlights the possible problem when developing ASP.NET websites while using VSDS instead of the local IIS.

Also, refer to this post by myself about how to handle error messages with IIS7, if you wish to have full control of the error output.

Summary:

  • Developing in VSDS - use customErrors
  • Publishing the site to IIS6 - use customErrors
  • Publishing the site to IIS7 - use httpErrors.

and if you develop with VSDS but publish to IIS7, then i guess u'll need both.

3
  • 32
    customErrors are for asp.net. httpErrors are for IIS7, and so handle content that doesn't go through the .net handler (e.g. .png, .js etc.) If you want error pages for non-.net content types, use IIS error pages (httpErrors for IIS7, the UI for IIS6.)
    – zcrar70
    May 24, 2011 at 8:53
  • 4
    I recommend installing and using IIS 7 Express with Visual Studio for debugging purposes. It will use the same config options as regular IIS 7, unlike Cassini.
    – Sean
    Nov 5, 2011 at 21:37
  • it is no longer necessary to use customErrors by @johnB . And too necessary? 1.) enable "Send Errors to Browser" under "ASP" section. the Debugging Properties 2.) under "Error Pages / Edit Feature Settings", select "Detailed errors". 3.) disable "Show friendly HTTP error messages" in IE stackoverflow.com/questions/2640526/…
    – Kiquenet
    Oct 6, 2015 at 19:38
40

<customErrors> versus <httpErrors>


<customErrors>

  • still available in IIS7+
  • specify custom error pages for requests handled by ASP.NET
  • only handles requests within the ASP.NET application
  • static files such as HTML files or directory (“friendly”) URLs are not handled

<httpErrors>

  • introduced in IIS7
  • specify custom error pages for requests handled by IIS
  • handles requests within the ASP.NET application AND/OR handles requests outside the - ASP.NET application *
  • all files and URLs are handled *

Note: it is no longer necessary to use customErrors

Quoted source: Custom 404 and error pages in ASP.NET (excellent article)


ExecuteURL serves dynamic content such as an .aspx page (the path value has to be a server relative URL):

<system.webServer>
  <httpErrors errorMode="Custom" existingResponse="Auto" defaultResponseMode="ExecuteURL" >
    <remove statusCode="404"/>
    <error statusCode="404" responseMode="ExecuteURL" path="/error.aspx" />
  </httpErrors>
</system.webServer>

File serves a custom error file, such as a .html page:

<system.webServer>
  <httpErrors errorMode="Custom" existingResponse="Auto" defaultResponseMode="File" >
    <remove statusCode="404"/>
    <error statusCode="404" path="404.html" />
  </httpErrors>
</system.webServer>

Reference: HTTP Errors (www.iis.net)

for more details, read the www.iis.net link above

2
  • Maybe useful ** stackoverflow.com/questions/2640526/…** if combine httpErrors with "Send Errors to Browser" and Error Pages
    – Kiquenet
    Oct 6, 2015 at 19:45
  • 4
    +1 for the note it's no loger necesary to use customErrors and the citation, this is really the info I was after :-)
    – Myster
    Oct 29, 2015 at 1:34
4

Errors section in web config is for providing custom http error handling approach there are two section, one customErrors inside the section system.web and another httpErrors inside the section system.webServer (as given below)

customErrors : This section was in use before IIS 7 introduced, IIS 6 5 and before fully use this section for handling custom http errors according to http status code.

httpErrors : IIS 7 and later use this section as well as customErrors section to handle custom http errors based on their file extensions if requested page extension register with ISAPI dll (.aspx, ashx, .asmx, .svc etc) like index.aspx then IIS pick up setting from customeErrors section else it pick up setting from httpErrors (IIS 7 hosted mode must be set as integrated mood not classic)

below are the examples that is for 404 error handling check link :

httperrors vs customerrors in webconfig , iis, asp.net

Your Answer

By clicking “Post Your Answer”, you agree to our terms of service and acknowledge that you have read and understand our privacy policy and code of conduct.

Not the answer you're looking for? Browse other questions tagged or ask your own question.