# Custom error pages

## Overview

Custom error pages have a role for your website security and user browsing experience. In case your Sitefinity CMS website encounters a problem, your database server goes down, or your custom code throws an error, the user browsing the site is presented with an error screen. This error screen is also known as YSOD or the “yellow screen of death”. This is the default ASP.NET error screen that can contain sensitive information and make it visible to the public, for example your connection string or important variable names.

You must configure error pages to make sure such information is not visible on the live site. Additionally, error pages provide a much better way of informing the users that there is a problem with the resource they are trying to access.

## Enable custom error pages

By default, for projects created on Sitefinity CMS 12.2 or later, custom error pages are enabled. For projects created with a version lower than 12.2 and then upgraded to version 12.2 or above, custom error pages are disabled.

You configure error pages in the advanced *Settings* screen. Perform the following:

1. In Sitefinity CMS backend, navigate to *Administration* » *Settings* » *Advanced*.
2. In the left tree, expand *Pages* and click *Custom error pages*.
3. To enable custom error pages, select one of the following:
   * *Enabled*\
     The system displays the configured custom error pages to all users – remote and localhost.
   * *RemoteOnly*\
     The system displays the configured custom error pages to remote users. To localhost users, the system displays the default ASP.NET error pages – the YSOD.
4. To disable custom error pages, select *Disabled*.\
   The system displays the default ASP.NET error pages to all users – the YSOD.
5. Save your changes.

## Map error codes to custom error pages

> info **NOTE**: You have one preconfigured error type – error type *404* page not found. However, this does not mean that you automatically have working custom 404 page. To complete the process, you need to create a Sitefinity CMS page with URL *\~/404*.

1. In Sitefinity CMS backend, navigate to *Administration* » *Settings* » *Advanced*.
2. In the left tree, expand *Pages* » *Custom error pages* and click *Error types* » *Create new*.
3. In *HTTP status code*, enter the code of the error type.\
   For example, enter `403`

   For complete list of supported error codes, see [Supported error codes](https://www.progress.com/documentation/sitefinity-cms/administration-custom-error-pages#supported-error-codes).
4. In *Error page URL name*, enter the exact URL of the page that you intend to use as custom error page.\
   This is a normal Sitefinity CMS page that contains the information that you want to display when the error type is encountered.
5. You enter the URL name in one of the following ways:
   * Only the URL name of the page\
     For example, if the page URL is *\~/403-forbidden*, in *Error page URL name*, enter `403-forbidden`

     This allows you to use different error pages in different directories of your website. This way, you can translate your page, if you use multiple languages. You can also display different pages for the same error code, depending where the user’s request has produced the error.

     For more information about the behavior of the error pages, see [Create the error pages](https://www.progress.com/documentation/sitefinity-cms/administration-custom-error-pages#create-the-error-pages) and the provided example.
   * A directory, followed by the URL name of the page\
     You can also enter a directory, followed by the exact URL of the error page. This means that your error page is located under another page or group page. For example, you can have all of your error code pages under a group page *Error pages* with URL *\~/error-pages*.

     In this case, as URL name, you must enter `/error-pages/403` and you must create the custom error page as a child of *Error pages* page.
   * The URL name of the page, preceded by tilde\
     If you do not want to use different error pages for the same error code or you do not want to translate your custom error page, enter the exact location of your page with tilde.

     For example, if your page is located on root level, under page *Error pages*, enter `~/error-pages/403`
6. Select *Redirect* checkbox, if you want the user to be redirected to the actual error page’s URL.\
   For example, *\~/403-forbidden*. Otherwise, the error page is rendered on the URL that the user is currently trying to open.

   > info **RECOMMENDATION**: We recommend leaving *Redirect* checkbox deselected.
7. Save your changes.

> success **EXAMPLE**: If you want to configure a 403 custom error page that informs the user that the requested service is forbidden, perform the following:
>
> 1. Make sure custom error pages are enabled.
> 2. Navigate to *Administration* » *Settings* » *Advanced* » *Pages* » *Custom error pages* » *Error types* » *Create new.*
> 3. In *HTTP status code*, enter `403`
> 4. In *Error page URL name*, enter `forbidden-403`
> 5. Save your changes.
> 6. Navigate to *Pages*.
> 7. Create a page with title *Forbidden 403* and URL – *\~/forbidden-403.*
> 8. On this page, create the content that you want to display to users that request a service that is they do not have permissions for.

## Create the error pages

You create the required error pages as normal Sitefinity CMS pages. The only requirement is to follow the URL names that you have already configured in the *Advanced* settings for *Custom error pages*.

For the same error code, you can have different error pages for different sections of your website.\
The following example demonstrates the priorities for displaying different error pages for the same error code.

> success **EXAMPLE**: You have a website with two sections, represented by group pages *ABC* and *XYZ*. In both sections you have a number of pages and you also have some other pages on root level.\
> Therefore, the URL names of your website pages are as follows:
>
> * Pages inside section *ABC* have URLs in the format of *[www.yoursitedomain.com/abc/page-url-name](http://www.yoursitedomain.com/abc/page-url-name)*
> * Pages inside section *XYZ* have URLs in the format of *[www.yoursitedomain.com/xyz/page-url-name](http://www.yoursitedomain.com/xyz/page-url-name)*
> * All other pages on root level have URLs in the format of *[www.yoursitedomain.com/page-url-name](http://www.yoursitedomain.com/page-url-name)*
>
> In the *Advanced* settings you have configured a custom error page *404* for page not found error and you have entered the *Error page URL name* of `404`. You want to have specific 404 custom error page that is displayed to user that are browsing section *ABC* and another 404 custom error page for all other pages of the website, including the pages inside section *XYZ*.
> To accomplish this, inside section *ABC*, you create one page with title *ABC 404* that has URL in the format of *[www.yoursitedomain.com/abc/404](http://www.yoursitedomain.com/abc/404)*
> On root level, you create the other custom error page with title *General 404* that has URL in the format of *[www.yoursitedomain.com/404](http://www.yoursitedomain.com/404)*
> As a result, the system behaves in the following way:
>
> * If a user requests a page that does not exist inside section *ABC*, the system displays page *ABC 404*.\
>   That is, if the user requests a page with URL *[www.yoursitedomain.com/abc/non-existent-page](http://www.yoursitedomain.com/abc/non-existent-page)*, the system checks for a page with URL *[www.yoursitedomain.com/abc/404](http://www.yoursitedomain.com/abc/404)*, find it, and displays page *ABC 404*.
> * If the user requests a page that does not exist inside section *XYZ*, the system checks for a page with URL *\~/404* inside section *XYZ*, because such page does not exist in section *XYZ*, the system checks for a page with URL *\~/404* on the upper level, which, in this case, is the root level. The system finds page *General 404* and displays it to the user.\
>   That is, if the user requests a page with URL *[www.yoursitedomain.com/xyz/non-existent-page](http://www.yoursitedomain.com/xyz/non-existent-page)*, the system checks for a page with URL *[www.yoursitedomain.com/xyz/404](http://www.yoursitedomain.com/xyz/404)*. When the system does not find such a page, it checks for a page with URL *[www.yoursitedomain.com/404](http://www.yoursitedomain.com/404)*, finds it, and displays page *General 404*.
> * If the user requests a page that does not exist on the root level of you website, the system checks for a page with URL *\~/404* on root level and displays page *General 404*.\
>   That is, if the user request a page with URL *[www.yoursitedomain.com/non-existent-page](http://www.yoursitedomain.com/non-existent-page)*, the system checks for a page with URL *[www.yoursitedomain.com/404](http://www.yoursitedomain.com/404)*, finds it, and displays page *General 404*.

### Relative error page path

The same behavior will apply, if instead of 404, you have entered as *Error code URL name* `/error-pages/404` and have created page *ABC 404* inside section *ABC*, under page *Error pages* and page *General 404* – under another page named *Error pages* on root level. In this case, the system will first look for the error page on the same level, but under the parent page *Error pages*.

### Absolute error page path

If you want to override the behavior described in the example, in *Error page URL name*, you can specify the URL name of the page with tilde – for example, you can enter `~/403`

In this case, the system will look for the respective error page only on root level. If you enter `~/error-pages/403`, the system will look for a page with URL *403* on root level, under page *Error pages*.

## Custom error pages and multiple languages

You can use the logic in the previous example to translate custom error pages.

You first configure the error code by matching it to a particular URL. Then, you create different pages in the different language directories with the same URL.

> success **EXAMPLE**: You site is translated in English and German and you want to have two different versions of the 404 error page. You create the English page and then translate it to German.\
> The result is the following:
>
> * You have the English 404 error page with URL of the format *[www.yoursitedomain.com/en/404](http://www.yoursitedomain.com/en/404)* and you display it to users that search for a non-existent page in the English version of your website.
> * You have the German 404 error page with URL of the format *[www.yoursitedomain.com/de/404](http://www.yoursitedomain.com/de/404)* and you display it to users that search for a non-existent page in the German version of your website.

## Default error pages

If you want to configure individual custom error pages for some codes and one generic custom error page for all others, you can do that using a *Default* page. This way, whenever the system encounters an error for which you do not have a specific custom error page, the system will search and fallback to the default one.

Default custom error pages work the same way as all other custom error pages.

To configure a Default custom error page, perform all of the above procedures, but in fields *HTTP status code*, enter `Default`

## Supported error codes

Following is a list of error codes that you can configure in Sitefinity CMS. These are the values that you can enter in field *Administration* » *Settings* » *Advanced* » *Pages* » *Custom error pages* » *Error types* » *Create new* » *HTTP status code*.

 <table>
<tbody>
<tr>
<td>

<strong>HTTP status code</strong><br>

</td>
<td>

<strong>Meaning</strong><br>

</td>
<td>

<strong>Description</strong><br>

</td>
</tr>
<tr>
<td>

400

</td>
<td>

Bad request<br>

</td>
<td>

<code>HttpErrorCode.BadRequest</code> indicates that the request could not be interpreted by the server.

<p><code>HttpErrorCode.BadRequest</code> is sent when no other error is applicable, or if the exact error is unknown or does not have its own error code.</p>

</td>
</tr>
<tr>
<td>

402<br>

</td>
<td>

Payment required<br>

</td>
<td>

<code>HttpErrorCode.PaymentRequired</code> is reserved for future use.<br>

</td>
</tr>
<tr>
<td>

403<br>

</td>
<td>

Forbidden<br>

</td>
<td>

<code>HttpErrorCode.Forbidden</code> indicates that the server refuses to fulfill the request.<br>

</td>
</tr>
<tr>
<td>

404<br>

</td>
<td>

Not found<br>

</td>
<td>

<code>HttpErrorCode.NotFound</code> indicates that the requested resource does not exist on the server.<br>

</td>
</tr>
<tr>
<td>

405<br>

</td>
<td>

Method not allowed<br>

</td>
<td>

<code>HttpErrorCode.MethodNotAllowed</code> indicates that the request method (<code>POST</code> or <code>GET</code>) is not allowed on the requested resource.<br>

</td>
</tr>
<tr>
<td>

406<br>

</td>
<td>

Not acceptable<br>

</td>
<td>

<code>HttpErrorCode.NotAcceptable</code> indicates that the client has indicated with <code>Accept</code> headers that it will not accept any of the available representations of the resource.<br>

</td>
</tr>
<tr>
<td>

407<br>

</td>
<td>

Proxy authentication required<br>

</td>
<td>

<code>HttpErrorCode.ProxyAuthenticationRequired</code> indicates that the requested proxy requires authentication. The <code>Proxy-authenticate</code> header contains the details of how to perform the authentication.

</td>
</tr>
<tr>
<td>

408<br>

</td>
<td>

Request timeout<br>

</td>
<td>

<code>HttpErrorCode.RequestTimeout</code> indicates that the client did not send a request within the time the server was expecting the request.<br>

</td>
</tr>
<tr>
<td>

409<br>

</td>
<td>

Conflict<br>

</td>
<td>

<code>HttpErrorCode.Conflict</code> indicates that the request could not be carried out because of a conflict on the server.

</td>
</tr>
<tr>
<td>

410<br>

</td>
<td>

Gone<br>

</td>
<td>

<code>HttpErrorCode.Gone</code> indicates that the requested resource is no longer available.<br>

</td>
</tr>
<tr>
<td>

411<br>

</td>
<td>

Length required<br>

</td>
<td>

<code>HttpErrorCode.LengthRequired</code> indicates that the required <code>Content-length</code> header is missing.<br>

</td>
</tr>
<tr>
<td>

412<br>

</td>
<td>

Precondition failed<br>

</td>
<td>

<code>HttpErrorCode.PreconditionFailed</code> indicates that a condition set for this request failed, and the request cannot be carried out. Conditions are set with conditional request headers like <code>If-Match</code>, <code>If-None-Match</code>, or <code>If-Unmodified-Since</code>.<br>

</td>
</tr>
<tr>
<td>

413<br>

</td>
<td>

Request entity too large<br>

</td>
<td>

<code>HttpErrorCode.RequestEntityTooLarge</code> indicates that the request is too large for the server to process.<br>

</td>
</tr>
<tr>
<td>

414<br>

</td>
<td>

Request Uri too long<br>

</td>
<td>

<code>HttpErrorCode.RequestUriTooLong</code> indicates that the URI is too long.<br>

</td>
</tr>
<tr>
<td>

415<br>

</td>
<td>

Unsupported media type<br>

</td>
<td>

<code>HttpErrorCode.UnsupportedMediaType</code> indicates that the request is an unsupported type.<br>

</td>
</tr>
<tr>
<td>

416<br>

</td>
<td>

Requested range not satisfiable<br>

</td>
<td>

<code>HttpErrorCode.RequestedRangeNotSatisfiable</code> indicates that the range of data requested from the resource cannot be returned, either because the beginning of the range is before the beginning of the resource, or the end of the range is after the end of the resource.<br>

</td>
</tr>
<tr>
<td>

417<br>

</td>
<td>

Expectation failed<br>

</td>
<td>

<code>HttpErrorCode.ExpectationFailed</code> indicates that an expectation given in an Expect header could not be met by the server.<br>

</td>
</tr>
<tr>
<td>

426<br>

</td>
<td>

Upgrade required<br>

</td>
<td>

<code>HttpErrorCode.UpgradeRequired</code> indicates that the client should switch to a different protocol such as TLS/1.0.<br>

</td>
</tr>
<tr>
<td>

500<br>

</td>
<td>

Internal server error<br>

</td>
<td>

<code>HttpErrorCode.InternalServerError</code> indicates that a generic error has occurred on the server.<br>

</td>
</tr>
<tr>
<td>

501<br>

</td>
<td>

Not implemented<br>

</td>
<td>

<code>HttpErrorCode.NotImplemented</code> indicates that the server does not support the requested function.<br>

</td>
</tr>
<tr>
<td>

502<br>

</td>
<td>

Bad gateway<br>

</td>
<td>

<code>HttpErrorCode.BadGateway</code> indicates that an intermediate proxy server received a bad response from another proxy or the origin server.<br>

</td>
</tr>
<tr>
<td>

503<br>

</td>
<td>

Service unavailable<br>

</td>
<td>

<code>HttpErrorCode.ServiceUnavailable</code> indicates that the server is temporarily unavailable, usually due to high load or maintenance.<br>

</td>
</tr>
<tr>
<td>

504<br>

</td>
<td>

Gatewaytimeout<br>

</td>
<td>

<code>HttpErrorCode.GatewayTimeout</code> indicates that an intermediate proxy server timed out while waiting for a response from another proxy or the origin server.<br>

</td>
</tr>
<tr>
<td>

505<br>

</td>
<td>

HTTP version not supported<br>

</td>
<td>

<code>HttpErrorCode.HttpVersionNotSupported</code> indicates that the requested HTTP version is not supported by the server.<br>

</td>
</tr>
</tbody>
</table>

## Configure internal server error 500

By default, custom error pages, configured in the advanced settings, override custom error pages, configured in the `web.config` file. However, if an internal server error occurs before this logic is executed, the system will throw the default ASP.NET internal server error.

> info  **RECOMMENDATION**: Therefore, in addition to having a 500 custom error page, configured in the advanced settings, we recommend configuring an additional 500 custom error page in the `web.config` file.

You configure custom error pages via the `web.config` using the `<httpErrors>` and `<customErrors>` configuration elements.

### Configure the \<httpErrors> element

The `<httpErrors>` is an element inside your web.config file. It represents the error pages configuration in IIS, and has been introduced with IIS 7. HttpErrors handles errors that occur when accessing Sitefinity CMS pages, for example URLs like **/mysite/foo**.

To configure `<httpErrors>` for your Sitefinity CMS website follow this procedure:

1. Open the web.config file that is in your project’s folder.
2. Find the `<system.webServer>` config section
3. Configure the `<httpErrors>` section. The sample below demonstrates handling the 500 error code:
   ```XML
   <httpErrors errorMode="Custom">
         <clear />
         <remove statusCode="500" subStatusCode="-1" />
         <error statusCode="500" path="/error-pages/500" responseMode="ExecuteURL" />
   </httpErrors>
   ```

### Configure the \<customErrors> element

The `<customErrors>` element controls the behavior for errors thrown by ASP.NET during the execution of a request. For example, errors thrown when serving static resources (e.g. \*.aspx pages, images, etc.)

To configure `<customErrors>` for your Sitefinity CMS website follow this procedure:

1. Find the `<system.web>` config section in your web.config file
2. Add the following `<customErrors>` section to handle the 500 error code:

   ```XML
   <customErrors mode="RemoteOnly">
         <error statusCode="500" redirect="~/error-pages/500" />
   </customErrors>
   ```

   This `<customErrors>` section above handles errors when accessing ASP.NET files (for example `.aspx` files). The paths to the error pages are virtual relative paths.
3. Save and close the `web.config` file.
