Create custom error pages in Sitefinity

Custom error pages are one of the major steps that you need to take care when you create a website no matter the platform. Most of you already know how to add .html custom error pages through the section in the web.config. The following blog post will provide explanation and steps to create Sitefinity pages for 404, 403 and 500 response status codes.

Download the full code from Github repository here.

What are the benefits in using Sitefinity pages when receiving errors:

  • Ability to display error page using the same fashion as for the whole site - themplates, themes, etc.
  • Support for multilingial translation


1.Create pages structure

Create the following structure of pages in Sitefinity as shown in the picture below:

Sitefinity pages structure

2.Add error page content

You can put any content that you want in the pages. For example:

Drag a Content block control in the 404 page and type the following text:

404 text

3.Open your web.config file and put the following settings to configure customErrors section:

a) Before the end of the system.web section and after the end of httpModules section add:

<customErrors mode="On">
  <error statusCode="500" redirect="~/error-pages/500" />
  <error statusCode="404" redirect="~/error-pages/404" />
  <error statusCode="403" redirect="~/error-pages/403" />

TIP:Mode is set to On to test the error pages locally. Do not forget to change it to RemoteOnly when in poduction. For more information see MSDN article.

b) Before the end of the system.WebServer section and right after the end of security section add:

<httpErrors errorMode="Custom">
  CUSTOM ERROR PAGES #2 (See #1 above)
  This part handles errors when accessing Sitefinity pages.
  The paths to the error pages are relative root and should include the virtual directory name.
  <clear />
  <remove statusCode="404" subStatusCode="-1" />
  <error statusCode="404" path="/error-pages/404" responseMode="ExecuteURL" />
  <error statusCode="403" path="/error-pages/403" responseMode="ExecuteURL" />
  <error statusCode="500" path="/error-pages/500" responseMode="ExecuteURL" />

Save the web.config file and you are ready to test your custom error pages.

Open your website in browser. Type and invalid url: e.g.: http://yourhost:XXXX/home-page/test1234
As a result, you will be redirected to the 404 page. Pay an extra attention to the response status code that is returned - 200 instead of 404.

Why is my 404 page returning 200 as a response status code?
Because after the redirect Sitefinity page 404 is found and is returning 200.

TIP: Be extremely careful for response status codes that you website returns or you might be punished by the search engines (e.g. your rank could be decreased). 404 page must return 404 response status code and not 200!

How to change the response status code to 404?

You can create a user control in your Sitefinity application that will explicitly change the response status code. Example:

public partial class NotFoundStatusCodeSetter : System.Web.UI.UserControl
    protected override void Render(HtmlTextWriter writer)
        if (!this.IsDesignMode())
            Response.Status = "404 Not Found";
            Response.StatusCode = 404;
            lblMessage.Text = "Sets the response status code to 404 explicitly on the front-end";

You must change the status code of the response only when not in design mode and before the page renders. Next, you must register the user control in Sitefinity and put it on the 404 page. See Sitefinity documentation article for how to register Sitefinity user control in the Toolbox.

How to programmatically register the user control?

You can benefit from one of the ASP.NET 4 Extensibility gems - PreApplicationStartMethodAttribute. Create new class that will be called before the application is started. Next, you can handle the SystemManager ApplicationStart method and use Sitefinity API to register custom section and control in the toolbox. See the code in Github repository.

TIP: Do not forget to restart your application for the PreApplicationStartMethodAttribute to be called.

Enjoy your custom errors!

Veronica Milcheva

I am a passionate Sitefinity blogger, developer and consultant. In my spare time I enjoy running and listening to music. My personal quote: There's no tough problem, just not enough coffee :)

Sofia, Bulgaria