A Complete Guide to Configuring Friendly Error Pages in Sitecore – Part 2 –500 Pages

August 24, 2017

Blog | Development | A Complete Guide to Configuring Friendly Error Pages in Sitecore – Part 2 –500 Pages

There are two main use-cases to account for while setting up friendly error pages in Sitecore (or any web-app for that matter).  Accounting for 404, Page Not Found errors has been covered at length in part 1 of this series.  This post will focus on the remaining use-case, 500 Internal Server Error pages. Internal sever errors are often referred to as Yellow Screens of Death (YSOD).  These pages output the stack trace of the application and can often give insight into the underlying pages logic.  It is imperative that a production site hides these errors from users and instead returns a friendly “Oops, an error occurred” style page.  It is also important that the underlying error is logged so that developers may seek to resolve the issue.

The code from this post has been packaged up as a NuGet package.

Configuration Updates

To handle 500 errors, aka Yellow Screens of Death, the following is added to the web.config, shown as a config transformation.

<?xml version="1.0" encoding="utf-8"?>
<configuration xmlns:xdt="http://schemas.microsoft.com/XML-Document-Transform">
    <customErrors mode="RemoteOnly" defaultRedirect="500.aspx" redirectMode="ResponseRewrite" xdt:Transform="SetAttributes">
      <error statusCode="500" redirect="500.aspx" xdt:Transform="Insert" />

This causes IIS to return our custom ~/500.aspx instead of the standard (ugly) IIS default page. We can then style this page as needed. This page contains the following markup at the top of the page:

    Response.StatusCode = 500;
    Response.TrySkipIisCustomErrors = true;

<!doctype html>

This ensures the response sent to the browser is 500.

These are all of the changes necessary for returning friendly 500 error pages.  Errors are logged to the standard Sitecore log file. One quick note: this solution is not multi-tenant enabled.  To account for this, the 500 page will require custom logic to drive the content of the page depending on the request host name.  This is not covered in this blog post.

If you have been following along from part 1, the complete configuration changes needed are listed below in their entirety.

Patch config (Sitecore.ServerErrors.config) listed in ~\app_config\include\:

<?xml version="1.0"?>
<configuration xmlns:patch="http://www.sitecore.net/xmlconfig/">
      <setting name="LayoutNotFoundUrl">
        <patch:attribute name="value">/404</patch:attribute>
      <setting name="ItemNotFoundUrl">
        <patch:attribute name="value">/404</patch:attribute>
      <setting name="RequestErrors.UseServerSideRedirect">
        <patch:attribute name="value">true</patch:attribute>
        <!-- Reads updated "RequestErrors.UseServerSideRedirect" value and transfers request to LayoutNoutFoundUrl or ItemNotFoundUrl, preserving requested URL -->
        <processor type="MyDll.CustomExecuteRequest, MyDll" resolve="true" patch:instead="*[@type='Sitecore.Pipelines.HttpRequest.ExecuteRequest, Sitecore.Kernel']"/>
        <!-- Sets a 404 status code on the response -->
        <processor type="MyDll.Set404StatusCode, MyDll" patch:after="*[@type='Sitecore.Pipelines.HttpRequest.EndDiagnostics, Sitecore.Kernel']">
      <appender name="404Appender" type="log4net.Appender.SitecoreLogFileAppender, Sitecore.Logging">
        <file value="$(dataFolder)/logs/404.log.{date}.txt"/>
        <appendToFile value="true"/>
        <layout type="log4net.Layout.PatternLayout">
          <conversionPattern value="%4t %d{ABSOLUTE} %-5p %m%n"/>
        <encoding value="utf-8"/>
      <logger name="Loggers._404Logger" additivity="false">
        <level value="INFO"/>
        <appender-ref ref="404Appender"/>

Web.config updates (shown as transformation):

<?xml version="1.0" encoding="utf-8"?>
<configuration xmlns:xdt="http://schemas.microsoft.com/XML-Document-Transform">
      <add verb="*" path="sitecore_media.ashx" type="MyDll.MediaRequestHandler, MyDll" name="Sitecore.MediaRequestHandler" xdt:Transform="Replace" xdt:Locator="Match(name)" />
    <httpErrors errorMode="DetailedLocalOnly" existingResponse="Auto" xdt:Transform="Insert" >
      <remove statusCode="404" subStatusCode="-1" />
      <!-- condition is met when Sitecore is unable to process request, e.g. with a completely foreign extenstion -> http://site.com/test.msklnd-->
      <error statusCode="404" path="404.html" responseMode="File" />
    <customErrors mode="RemoteOnly" defaultRedirect="500.aspx" redirectMode="ResponseRewrite" xdt:Transform="SetAttributes">
      <error statusCode="500" redirect="500.aspx" xdt:Transform="Insert" />

With these settings, your visitors should have an acceptable experience, even in non-ideal scenarios.

These updates have been tested/vetted on Sitecore 8.2 and Sitecore 9.

John Rappel

.NET Practice Lead
  • Error Pages
  • Sitecore
subscribe to GeekHive's newsletter

Never miss out on a Sitecore update again!

Our newsletter features a blog roundup of our top posts so you can stay up to date with industry trends, tutorials, and best practices.

Recent Work

Check out what else we've been working on