Custom Error Pages in SharePoint

As I alluded to in my post Exception Handling in SharePoint, providing custom error pages is an integral step in an overall exception handling strategy. This is particularly important for public facing internet sites to portray a consistent brand for the site in any situation, however is also relevant for intra or extranet portals to provide a more user-friendly experience and to reduce confusion in the event of an error. In similar fashion to my post on Error Logging in SharePoint, the information already available on this topic is extensive so the need for me to blog the specifics is negligible. This post will however join the link between my 2 previous posts mentioned above by outlining the best resources available in this area for both SharePoint 2007 and 2010.

In the ASP.NET world this topic would barely rate a mention. Handling this matter is essentially as simple as ensuring the <customErrors> mode=”” attribute is set to “On” and the defaultRedirect=”” attribute is set to a valid error page. We can’t use this method in SharePoint however as SharePoint has its own error handling infrastructure which overrides this functionality.

What we do have are different ways in which we can achieve this functionality in both versions of the product. When we talk of error pages in a SharePoint context we can group them into two categories for the purpose of identifying ways in which they can be addressed; 404 Page Not Found error pages and any others (which can include but are not limited to 401 Access Denied errors, 500 HTTP Status errors and the like).

404 Page Not Found

Microsoft has a knowledge base article How to point to a custom 404 error Web page in SharePoint which covers both versions of SharePoint. One thing to note here however is that it’s not necessary to create a console application to carry out the command in SharePoint 2007 – you can also use a powershell command to achieve the same thing noted in Ian Morrish’s post Using PowerShell to set a custom SharePoint Error Page.

Another thing to note is that this method requires the specified file to be valid HTML larger than 512 bytes in size. The size limitation is to ensure friendly HTTP error messages are not triggered in the client. I’ve also seen minorly-invalid HTML rendering as text in the browser so this is another thing to look out for. One more gotchya was identified by Andreas Glaser in SharePoint and custom 404 Page Not Found and UTF-8 issue with Firefox which is worth consideration.

One downside to the method presented above is that you are limited to static HTML pages deployed to the _layouts/1033 directory (or which ever LCID is appropriate for your site). This results in branding elements needing to be implemented in the static HTML and ensures maintenance of the page is more complicated than it should be. The main advice here is to implement a redirect on that error page to a standard SharePoint page along the lines identified by Jingmei Li in How to create your own custom 404 error page and handle redirect in SharePoint 2007 (MOSS)?.

There is another line of thought however, predominantly outlined by Waldek Mastykarz in his posts Accessible 404 (PageNotFound) in Microsoft Office SharePoint Server 2007 and SharePoint 2010 ‘Page not found (404)’ page the way it should be. This advocates using an HTTP Module to redirect the user to a page managed in SharePoint. If you’re going to go down this path focus on the second article and pay attention to Andrew Greaves’ comment.

While I like Waldek’s approach and appreciate its thoroughness in its flexibility for working in all scenarios and its technical correctness, for most purposes using the other method would suffice (particularly in controlled internal environments).

Other Error Pages

While the handling of 404 errors is quite similar in both SharePoint 2007 and 2010, the same cannot be said for other errors. SharePoint 2010 excels in this area providing an easy to use method of assigning these custom error pages at the web application level. Todd Carter provides a post titled An Expected Error Has Occurred which is well worth a read and while the code snippets are identical, Ram Prasad Meenavalli’s post Mapping Custom Error Pages for SharePoint 2010 Site is a good extension to it. Mike’s post SharePoint 2010 Custom Error Messages for Public Facing Deployments is a quality post particularly in terms of 401 authentication errors and is worth a look as well.

Implementing custom error pages for SharePoint 2007 however is not so simple. There seems to be 3 camps of thought; firstly there is the HTTP Module method similar to that used with the 404’s outlined above. While its a little difficult to read and follow, this method is documented in Ketaanh Shah’s post MOSS / Sharepoint 2007 Custom Error Page and Access denied Page. Another option is using a control adapter as per Aapo Talvensaari’s post Custom Error Page Adapter although i’d be a little wary implementing the functionality in this manner. My favourite option is Jeremy Jameson’s Error Handling in MOSS 2007 Applications which advocates hooking into the Error event from a custom master page – nice and clean, however it’s only really appropriate for errors that occur once the page has been accessed – i’m guessing it wouldn’t be suitable to handle errors such as a 401 authentication error.

In the interests of completeness there was one other form of configuring custom error pages I came across on Heath Anderson’s Implementing SharePoint 2010 Custom Error Pages. It is relevant to IIS7 and claims to work in SharePoint 2010 (whether it would work on an WSS instance installed on IIS7 i’m not sure). It definitely looks like a reasonably nice and clean option to consider, however it requires modifications to the web.config file even after configuring via the IIS UI and thus would not be the perfect option in my opinion.

So as you can see there are a bunch of ways in which you can implement custom error pages for your SharePoint site no matter which version of the product you are using. All methods vary in terms of their difficulty, suitability and correctness however the main takeaway is to ensure that you do use one of the methods and ensure that your users have the most user-friendly experience if they counter an error on your site.