The Art of Error Handling

Sometimes error handling seems to be the last thing we think about - if at all. 

The cause of this is maybe the lack of a good starting template for a new website. Or the "Happy flow" thought many developers have. If you know how things are supposed to work, you are unlikely to manually test other behavior.

With Umbraco, you typically have to think about two types of errors:

  1. Errors that occur inside Umbraco
  2. Errors that occur outside of Umbraco.

Let's start with the second category. This is a generic situation, unrelated to Umbraco. These errors occur in the context of Internet Information Services (IIS). There are many good tutorials that will help you deal with these kind of errors.

Now for the first category. Why would an error happen? 

The most common cause for an error is that the page url was stored by a user (for instance, as a favorite, or in his browser history) and since the page was renamed or taken offline. This scenario occurs frequently so the least you can do is take some precautions. 

This situation is really a 404 error type inside Umbraco. And in two simple steps here is the remedy.

First, create a page in the Umbraco back office. I usually use a generic document type, such as a text or content page, most often in a "Utilities" folder that is excluded from navigation (umbracoNaviHide = True). Assume the name of the page is "Oops" or "Error" or something similar. Note the id of the page. 

Make the page friendly and apologetic. It was not the user's fault that this happened!

Test the page just by previewing in Umbraco or browse to <sitename>/oops.

Now we need to change the umbracoSettings.config file in the config folder of the site.

In the errors section, add or modify the error404 node, as illustrated below, where 1234 stands for the id of the error handling page you just created. 

Error 404 node


There is much room for improvement here. First, using the id is not always a good idea. Using the GUID would be better.

Secondly, in multi-lingual websites it would be user friendly to signal an error in the language the user selected. So, you could make the error page dependent on the culture.