Skip to main content

Custom Error Pages

whoops

One of the important steps of any website is setting it up to fail Nicely. Sitecore has done a lot of this for us with their error pages, but that may not be the look you want your visitors to see! And what if Sitecore isn’t able to help at all? Not so pretty with ASP.NET error pages…

But do not fear! With the configuration files Sitecore makes available, this is a snap to set up and fix.***

***You Will need to change the web.config file, so please back it up before making any changes suggested here!

The first and hardest step – make your error/not found pages that you want your visitors to see – these can be html pages, aspx pages, or even an existing page within Sitecore.

Quick Edit!-- As a commenter pointed out: using Sitecore pages for your 404/page not found type errors can allow you to make use of the Sitecore features for multilingual sites as well as analytics. Not to mention, it makes it very easy for business users to make the changes.

Usually Sitecore will handle your errors nicely, but if .NET explodes you will need to display something to the user that will Not fail, so I’d VERY STRONGLY recommend an html page for errors and not aspx pages: if there’s an error in the error page, you’re back to square one.

Upload these files to your Website directory or a subfolder within it – for our example we have saved the files in Website/ErrorPages/.

If you’re using Sitecore Items, set those up within your content tree and publish them (somewhere other than where your html error page resides to keep things simple).

Now for the magic: In the website folder is a folder called App_Config and inside that is the Include folder. This folder automagically updates the web.config with new settings – it doesn’t require anything to be restarted and immediately takes effect. Also – using these files instead of modifying the web.config directly means you can make web.config type changes in packages without completely destroying the site.

There should be a file in that directory called: SitecoreSettings.config.example

This is what we will be changing into SitecoreSettings.config and adding our custom ‘not found’ page details.

Currently the file looks like this, along with some comments describing the use of the file at the top:

<configuration xmlns:patch="http://www.sitecore.net/xmlconfig/">
<
sitecore>
<
settings>
<!--
REQUIRE LOCK BEFORE EDITING
If true, the user must have a lock on a document before
he can edit it, otherwise it is always ready for editing
-->
<
setting name="RequireLockBeforeEditing" value="false"/>

</
settings>
</
sitecore>
</
configuration>

We are going to erase this, and put in the following:

<configuration xmlns:patch="http://www.sitecore.net/xmlconfig/">
<
sitecore>
<
settings>
<
setting name="ItemNotFoundUrl">
<
patch:attribute name="value">/ErrorPages/404.html</patch:attribute>
</
setting>
<
setting name="LinkItemNotFoundUrl">
<
patch:attribute name="value">/ErrorPages/404.html</patch:attribute>
</
setting>
<
setting name="LayoutNotFoundUrl">
<
patch:attribute name="value">/ErrorPages/404.html</patch:attribute>
</
setting>
<
setting name="ErrorPage">
<
patch:attribute name="value">/ErrorPages/Error.html</patch:attribute>
</
setting>
</
settings>
</
sitecore>
</
configuration>

The above basically tells the web.config file to update the specified settings with our new and improved values.

You can choose other files to use or have different files for each – and these special pages do not stop any logging from happening on the server – they simply give a better experience for your users when your site is having some trouble. 

ItemNotFoundUrl and LinkItemNotFoundUrl will come up when a visitor tries to access an item that doesn’t exist or hasn’t been published (it doesn’t exist yet on the web database). This replaces the default value of: /sitecore/service/notfound.aspx with our own /ErrorPages/404.html

You’ll notice that the default is pulling from /sitecore/service Ăź if you have blocked this directory or don’t have it available, you will need to make the changes above so that users see Some kind of page instead of a browser default.

LayoutNotFoundUrl will come up when the user tries to visit an item that does exist, but no layouts have been assigned to the item so Sitecore doesn’t know what to display for the user. This replaces /sitecore/service/nolayout.aspx in the default web.config file.

ErrorPage should come up whenever there is a generic error within Sitecore – the default setting we are overwriting is: /sitecore/service/error.aspx

Save your new file without the .example extension and you should now see your custom error pages whenever you try to access missing items!

The next step is the change to the web.config for handling errors when sitecore can’t handle them for us – save a backup of your web.config and then open it up in an editor.

Here is what we are looking for:

<!--  CUSTOM ERROR MESSAGES
Set customError mode values to control the display of user-friendly
error messages to users instead of error details (including a stack trace):

"On" Always display custom (friendly) messages
"Off" Always display detailed ASP.NET error information.
"RemoteOnly" Display custom (friendly) messages only to users not running
on the local Web server. This setting is recommended for security purposes, so
that you do not display application detail information to remote clients.
-->
<
customErrors mode="On" />

Search for customErrors to find it quickly. It may also have one of the above settings, RemoteOnly or Off. I would recommend On or RemoteOnly if you won’t have visitors accessing the site locally.

We want to change the setting to also include a redirect to our new Error page:

<customErrors mode="RemoteOnly" defaultRedirect="/ErrorPages/Error.html"/>

Now, if anything serious should happen, your users will not end up seeing an ASP.NET error page telling them it is broken and will instead get to see a page of your choice! This should Not point to a page you have in Sitecore since it will not work in the case of ASP.NET failing.

Anyone have any tips on making the user experience better in the case of errors?

Comments

  1. Why not redirect it to /error/404.aspx so it will be redirected to a sitecore item (so you can edit content and display a different errorpage in another language in a multi language environment!

    gr,

    Robbert
    http://twitter.com/kayeeNL

    ReplyDelete
  2. When redirecting to pages within sitecore (as is often done with a page not found f.ex.) one should remember to associate the page with the correct Sitecore Analytics attribute so that it is shown in the Analytics reports. Then it is easy to follow up missing URLs and correct them using aliases or other redirecting logic.

    /Larre

    ReplyDelete
  3. Thank you for the comments! I've updated the original article with your suggestions. :)

    ReplyDelete
  4. Amy,

    Thanks for the comments in your article!

    Larre: You're right! In the Analyze tab, don;'t forget to set the Failure Actie to 'Page not Found', that way the 404 will show up in the analytics report, and you'll be able to see the page that was called which resulted in a 404 page.

    gr,

    Robbert

    ReplyDelete
  5. That isn't very good idea to use *.aspx pages for error pages.
    Sure, it is so convenient - there is possibility to handle almost all cases even showing different error pages depends on error code returned by SQL server or CRM :) But - ASP.NET application process can be brought down suddenly or have some strange "not-responding" state. It happens :)
    So, what is the best way - either use convenient .aspx pages or "stone-stable" static .html. Well, that's the question looks like this one: "To be, or not to be..." :)

    ReplyDelete
  6. This comment has been removed by a blog administrator.

    ReplyDelete
  7. This comment has been removed by a blog administrator.

    ReplyDelete

Post a Comment

Popular posts from this blog

Using the Source Property

For each of the properties in your template you can set a source for it, this isn’t always used but can improve user experience drastically when done throughout a site. The source field comes in to play whenever you are using any of the following fields: Droplink, Droplist, Droptree, File, Grouped Droplink, Grouped Droplist, Image, Multilist, Treelist, Rich text field and a number of others. There are various ways of setting these up to achieve different results – but in general you are using the source to limit the set of items that can be used, and this requirement can also help you determine what kind of field to use. For example, if you have a Set of items all split down into sub folders and want the content editor to make use of the tree, you could use a TreeList or Drop Tree, but if you just want a set of items without the opportunity to see where those items are – multilists or droplinks are the way to go. For Images you’re generally just specifying where to look for and put th

Determining Page Editor Status with Javascript

     Often you’ll need to know if you are inside or outside the Experience/Page Editor in order perform an action. If you are on the server-side in code-behind you can check the Sitecore.Context.PageMode to determine which mode you are in. But what about at runtime? Javascript per usual can save the day! Though you can find PageModes through the Sitecore object if it is available to the browser, it may not be there. Depending on how things have been set up with your solution, the Sitecore object may not return a null as would be expected when checking to see if you can access it. Instead Sitecore may be undefined.  Contrary to some examples on the web with only null checks, this quick little change in your script can correctly let you know if you are in the page editor: Just take a look to see if isPageEditor is true or false and you’re set!

Links as Items Redux!

Previously I had posted on how to set up items in your content tree to act as external links to other pages (for use with Navigation mainly – for example if you have a blog elsewhere but still want it listed in the main navigation). However, Ivan Buzyka pointed out some issues with the simple implementation so I added creating a better redirect to my ‘to do’ list for the blog. The time has come! Let’s pretend we are modifying an existing site, we don’t want to change the navigation so that won’t be covered here – we just want to update our layout to work a little more universally. Our new items need to be able to link to an internal, external or Media item reliably for display in our navigation. Our template will consist of similar things to last time: Link: General Link Nav Title: Text -> standard values: $name In Navigation: Checkbox ->standard values: checked Create the template, add in standard values for it with the above settings and now we can create our Layout which shou