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?

Labels:

Comments

  1. RobbertSeptember 17, 2010 at 3:43 AM

    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. Larre LändinSeptember 17, 2010 at 4:36 AM

    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. AmySeptember 17, 2010 at 11:02 AM

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

    ReplyDelete
  4. RobbertSeptember 21, 2010 at 2:39 AM

    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. Ivan BuzykaSeptember 29, 2010 at 3:17 PM

    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. AnonymousJanuary 27, 2022 at 3:37 AM

    This comment has been removed by a blog administrator.

    ReplyDelete
  7. AnonymousApril 4, 2022 at 11:29 AM

    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
38 comments
Read more

Web Forms for Marketers: Send Email

To have the save action for your form actually send email, you will need to change one of the settings, otherwise you will receive this error whenever submitting the form: We experience a technical difficulty while processing your request. Your data may not have been correctly saved. Also in your log (/data/logs/newest log file) you will see this error after the form has been submitted: Exception: System.Net.WebException Message: The remote name could not be resolved: 'example.host' Source: System at System.Net.ServicePoint.GetConnection(PooledStream PooledStream, Object owner, Boolean async, IPAddress& address, Socket& abortSocket, Socket& abortSocket6, Int32 timeout) at System.Net.PooledStream.Activate(Object owningObject, Boolean async, Int32 timeout, GeneralAsyncDelegate asyncCallback) at System.Net.PooledStream.Activate(Object owningObject, GeneralAsyncDelegate asyncCallback) at System.Net.ConnectionPool.GetConnection(Object owningObject, GeneralA
58 comments
Read more

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!
2 comments
Read more