Implementing SharePoint 2010 Custom Error Pages

By default, when an HTTP error is encountered (404 page not found, 401 access denied, etc.), IIS returns the HTTP error code to the browser.  The browser (or a plug-in such as Google Toolbar) then decides exactly what gets displayed to the user.  You can alter this behavior and customize SharePoint 2010 to display your own custom error page(s) for HTTP errors that are encountered on your site.  These custom error pages can be static (ie. html) or dynamic (ie. aspx).

There are multiple options for overriding the behavior of HTTP error handling in your SharePoint implementation.  Some options include directly modifying the web.config, utilizing the IIS management console, and developing custom HTTP modules.  This post will demonstrate how to override the handling of HTTP error code 404 (page not found) and display a dynamic page located on a SharePoint publishing site.  We’ll explore using IIS to make the changes, and we’ll also look directly at the web.config (if you’re short on time, you can jump directly to editing the web.config at the end of this post).

Remember to make a backup copy of the web.config file so that the original file may be restored in the event something goes terribly wrong.  (That never happens, right?)

Launch IIS (Start -> Run -> inetmgr).  Expand Sites and click on the desired SharePoint site.  You're presented with a number of icons for managing your site...double click the Error Pages icon as shown below.

IIS Error Pages Icon

The Error Pages dialog shows the current (default) mappings of HTTP error codes to their built-in custom pages.  So, in the event a site has been configured to display custom error pages and no other changes are made, these are the pages that will be served.  These custom pages are located in the inetpub/custerr/<LANGUAGE-TAG>/ directory.  For example, there's already a file called inetpub/custerr/<LANGUAGE-TAG>/404.htm.

Error Pages Dialog

We could edit the 404.htm file directly if we simply wanted to add a link or make some minor cosmetic changes to the page, but let's make things a bit more interesting and assign a dynamic (.aspx) page located on our SharePoint 2010 site to be displayed when a 404 is encountered.  By executing a dynamic page, this will allow us to perform some custom logic as well as remain consistent with our current SharePoint branding.

Important note…if you're overriding 404 error handling to display a custom page on the same site, make certain the page exists.  If the custom page doesn’t exist, therefore resulting in another 404 error, I imagine this to be a potential infinite loop situation.

Double click the line with the 404 error to view the Custom Error Page dialog shown below.

Custom Error Page Properties

Choose the radio button "Execute a URL on this site" and provide a URL to the dynamic page (in this case we've created a new page on our SharePoint publishing site called /Pages/404.aspx), then click OK.

Custom Error Page Properties

After clicking OK you'll notice the Error Pages list has been modified to reflect your changes as shown below.

Error Pages Dialog

At this point, IIS has modified the underlying web.config to include a section called httpErrors (which is added within the system.webServer section).

<httpErrors>
    <remove statusCode="404" subStatusCode="-1" />
    <error statusCode="404" prefixLanguageFilePath="" path="/Pages/404.aspx" responseMode="ExecuteURL" />
</httpErrors>


Unfortunately, IIS didn't go quite far enough for this to work correctly in our SharePoint deployment.  A slight change to the httpErrors element setting error mode to Custom will inform IIS to use our custom page as follows:

<httpErrors errorMode="Custom" existingResponse="Auto">
    <remove statusCode="404" subStatusCode="-1" />
    <error statusCode="404" prefixLanguageFilePath="" path="/Pages/404.aspx" responseMode="ExecuteURL" />
</httpErrors>

To implement SharePoint support of a custom 404 error page, you can skip the IIS management console portion and jump directly to editing the web.config of the desired site.  Simply add the code snippet above to the system.webServer section and replace /Pages/404.aspx with your own dynamic page.

Comments for Implementing SharePoint 2010 Custom Error Pages


Name: shajan
Time: Thursday, March 29, 2012

Excellent

Name: Brad Young
Time: Wednesday, September 5, 2012

This doesn't seem to work for me when I add .aspx on to the end of my URL. Broken links are re-routed correctly in all cases until I add .aspx. Do you know why that might be? What should the customErrors look like in our web.config after this addition. Thanks!

Name: Fran
Time: Friday, September 21, 2012

When I add the errorMode="Custom" line - the website no longer renders says it has a programming error. Remove it it renders but no custom error file. Did I miss a step?

Name: Fran
Time: Friday, September 21, 2012

Should mention that I saved it as a html page extension not aspx.

Name: price
Time: Tuesday, September 25, 2012

This works great for me whereas no other suggestions did--not even the way specified by Microsoft. HOWEVER, if you land on the 404 page because of a bum url, the search on that page doesn't work. I believe it's because the form action is switched to some long url. If I load the 404.aspx page by itself, search works fine. Any suggestions?

Name: Heath Anderson
Time: Tuesday, September 25, 2012

Brad - The customErrors section has one property/value: mode="On"

Fran - Did you try copying and pasting the httpErrors section included above into your web.config (as the last element in the system.webServer section...so just above the closing system.webServer tag) and replacing the path with the path to your custom error html page? When I've made a change to the web.config and a site stops working, its typically an issue with the change I've made, such as an invalid character, a missing ending tag, a misspelling, etc.

Price - I've tested in my environment and search is working ok from the custom 404 page. The form action does include the extra url content, but it seems to function ok. What is the error you are receiving?

Name: Johan
Time: Tuesday, October 16, 2012

Following your example, I get a 500 Internal server error when I make the changes in the web.config file. Something like Fran above. If I undo the changes, it returns to the usual error page.

If I use the code as is (copied from your example for the 404) there is no issue but changing to 401.2 makes it break.

I would like to catch the 401.2 error when the user clicks on the cancel button instead of logging on in the credentials box.

What could be wrong here ? My web.config file:

















Name: Johan
Time: Tuesday, October 16, 2012

This is the error page I want to handle.

Server Error in '/' Application.
Access is denied.
Description: An error occurred while accessing the resources required to serve this request. The server may not be configured for access to the requested URL.

Error message 401.2.: Unauthorized: Logon failed due to server configuration. Verify that you have permission to view this directory or page based on the credentials you supplied and the authentication methods enabled on the Web server. Contact the Web server's administrator for additional assistance.

Version Information: Microsoft .NET Framework Version:2.0.50727.5456; ASP.NET Version:2.0.50727.5456

Name: Heath Anderson
Time: Monday, October 22, 2012

Johan - Unfortunately, your web.config didn't come through on the post. However, the issue could be related to the substatus code. Start with trying to get a custom error page to display for all 401's by replacing only the "404" with "401" (leaving the substatus code as -1). Once you are able to verify all 401 pages can be overridden, modify the web.config to include a substatus code (ie. 401.2). This should help begin to isolate the issue.

Name: BGM
Time: Saturday, January 12, 2013

Hello! This will work for me for 404 and 403, but when I do it for the 401, the sharepoint site won't accept my login any more. It gives me the login box over and over and over without ever resolving. But if I restore the custom 401 to default, it works fine. (sp 2010 enterprise, iis7.5 on windows server 2008r2)

Leave a comment





Captcha