When I have a problem and I spend a few hours scouring the internet only to find nothing related, I'm forced to draw one of three conclusions:

  1. I'm searching for the wrong thing.
  2. No one else has had this problem before. Ever.
  3. It isn't a real problem and I've done something dumb to get myself into a pickle.

I'm not sure which one this problem fits into, but I hope it will help someone anyways.

We recently implemented friendly error pages into our ASP.NET MVC app, which was a pain in of itself. Ben Foster outlined nicely the problems and a very nice solution on how to do this in this blog post. Thank you sir, for doing it right and sharing it with the world.

These worked beautifully until we tried to do a deployment. We pushed our app_offline.htm file to take the site offline, and instead of the nicely designed "Site undergoing maintenance" page, we saw this piece of junk:

The service is unavailable

The service is unavailable

Well, that's fantastic. After some troubleshooting we realized if we turned off httpErrors:

<httpErrors errorMode="Off" existingResponse="Replace">

The app_offline.htm page would work. How interesting? It seems that error codes not handled in this httpErrors section just output the default HTTP status code message. In this case, 503: The service is unavailable.

So, we can simply just handle 503 errors here:

<httpErrors errorMode="Custom" existingResponse="Replace">
    <remove statusCode="404"/>
    <error statusCode="404" path="404.html" responseMode="File" />
    <remove statusCode="500"/>
    <error statusCode="500" path="500.html" responseMode="File" />
    <remove statusCode="503"/>
    <error statusCode="503" path="app_offline.htm" responseMode="File" /> 

In theory, the only time a 503 is returned is when the app_offline.htm is present, so this works beautifully for us. Hope it works for you too!

Cheers, Rich
By Richard Rout
Only used for Gravatar avatar.