Improving Custom Errors for IIS7 Server

Another one of my favorite features is the IIS7 Detailed Errors feature.  Thomas wrote a great article titled Understanding Custom and Detailed Errors which provides a good overview of this simple, yet powerful feature.  (though it needs to be updated for RC1+) 

In using IIS7 the past two years, while it has been under development, I can honestly say that Detailed Errors are the single biggest help in making IIS easier to use.  If you haven't read Thomas' article yet, let me summarize how Detailed Errors works:

By default IIS now returns two kinds of errors when a problem occurs.  The first kind you are used to if you've used IIS before.  They are our standard custom errors, which a terse error description and error code.  If you don't like how our custom errors look, you can always configure IIS to return your own custom error message and away you go.  The second kind of error we now call "Detailed Error" which, by default, we only return to requests from localhost.  You can also configure IIS to return detailed errors all the time (if you want the application in debug mode) or to never return detailed errors - always return custom errors (if you get annoyed by our debug information). 

Here is a screenshot of the administration UI for this feature, which is pretty straightforward: 

Error Pages UI (click for full size image)

Note:  the schema for this feature changed slightly between Beta 2 and RC1.  The config section for this feature is <httpErrors> and the errorMode attribute descripes which behavior to use on the server.  Here is the relevant schema:

<sectionSchema name="system.webServer/httpErrors">
    <attribute name="errorMode" type="enum" defaultValue="DetailedLocalOnly">
        <enum name="DetailedLocalOnly" value="0" />
        <enum name="Custom" value="1" />
        <enum name="Detailed" value="2" />


The detailed error information we return is pretty darn helpful.  It includes a bunch of details about the request, like which pipeline notification the error occured during, which module and / or handler threw the error, the physical path which was processed for the request, the logon user and method (if available), and  more goodies.  Even better than that, we do our best to provide possible causes that lead to the error, based on the error code, sub-error code, and win32 hresult returned from the offending party.  And even better, we also try to give you some help in terms of next steps you should take to resolve the problem.  And last, if those don't work, we also provide a "more information" link which hooks up to our error database (not yet online) which will return the latest troubleshooting instructions we have for the particular error you've encountered!  Now that is cool.  Here is a sample of one particular error that I end up running into from time to time, when I type too fast and end up with invalid XML in my web.config file.  Notice how it even tells me where the XML problem occured:

Server 500 Error - Vista Edition (click for full size image)


And so this is how detailed errors works, and what you can expect in Vista.  One of the bits of polish we're working on for IIS7 in Longhorn Server (and will also most likely get updated in SP1 of vista) is a cleaner look for the error pages to make them easier to read.  I wanted to provide a preview of the current mock-ups and ask for your feedback.  What do you think, are they an improvement?  What would you do different?


The same Server 500 Error - Draft for Longhorn Server Edition (click for full size image)

Here is another example of a Server 401 error. Note the "most likely cause" and "things to try" sections:


Server 401.1 Error - Draft for Longhorn Server Edition (click for full size image)


So what do you think?  Are these an improvement?  Leave your comments below.


  • This sounds really nice and should make my life troubleshooting much easier. On a related not I'd be interested in seeing what improvements have been made in IIS7 for logging.

    Both of the screen shots look really nice. The second one looks a little long but then again it has lots of good information. Would it be possible to have each of those sections be collapsible? I'm thinking of the way IE7 has the "More Information" section that you can expand on a 404 error or the "Show more tab shortcuts" section when you hit Ctrl+T to open a new tab.

    Maybe have the "Most likely causes", "What you can try", and "Links & More Information" sections collapsed by default and the "Error Summary" and "Detailed Error Information" sections expanded by default.

  • I like the proposed formatting MUCH better. It is a lot cleaner, provides a nice segmentation of the details and therefore makes it easier for me to find what I am looking for. Very helpful to have the offending module and the links to the error database. Very cool stuff.

  • Looks very useful. Can we also add information to the error database ourselves? Some moderation would be in order but do you think this would be a good idea in essence?

  • Tom - that is a great idea. I'll be sure to pass it along to the guys who are designing the error database to make sure to think about doing that. at a minimum we will provide the ability to send feedback on the errors. thanks!

  • The new look is a huge improvement, and I also like Tom's idea from above. I'm curious if the 'Things to try' could also be extended for the errors so in scenarios on a hosted environment we could plug in our own 'things to try' that related to the hosted package they've purchased. Somewhat along the same concept used in the MOM 2005 tool where you can plug in your own troubleshooting information.

    Great stuff !!!

  • Thanks Chris! Glad you like them. While you can't extend the 'things to try', you can customize the 'view more information' link to have it point to your own database. maybe that gets you close enough?

  • Understood. When you say customize the link would that link be statically defined or is there a way to append which exception/error happened and potentially another attribute like which environment (i.e. product code)?

    It's still good to know that it's customizable and we can route the user to our system for more help.

    Thanks Bill.

  • ASP.Net error pages are way better than the old asp error ones and these ones you are proposing is definitely a step up. What I would suggest is a less graphicy interface. maybe something simpler. (but that's just my taste).

    Maybe the ability to expand and collapse the blocks.
    I also like the idea of being able to customize the blocks like with more information and/or add more blocks.

  • Chris - unfortunately there won't be a way to append more data to the errors, that information is baked into the detailed errors module at compile time. but the 'more information' link is customizable, so you can point users at it for any additional info.

    Hatim - the new errors don't use any graphics and are pretty simple HTML/CSS, but I can see how some may not like them. As always, it is hard to choose one style that everyone likes. But the good news is the 'custom errors', as always, are fully customizable so your customers will only see the errors as you want them to be seen. :)

  • don't make the headers (Error Summary, Detailed Error Information, etc.) look like buttons.

Comments have been disabled for this content.