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

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.

  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 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.

    RECOMMENDATION: We recommend leaving Redirect checkbox deselected.

  7. Save your changes.
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.

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
  • Pages inside section XYZ have URLs in the format of 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

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

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

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, the system checks for a page with URL 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, the system checks for a page with URL 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, 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, the system checks for a page with URL 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.

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 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 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.

HTTP status code
Meaning
Description
400 Bad request
HttpErrorCode.BadRequest indicates that the request could not be interpreted by the server.

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

402
Payment required
HttpErrorCode.PaymentRequired is reserved for future use.
403
Forbidden
HttpErrorCode.Forbidden indicates that the server refuses to fulfill the request.
404
Not found
HttpErrorCode.NotFound indicates that the requested resource does not exist on the server.
405
Method not allowed
HttpErrorCode.MethodNotAllowed indicates that the request method (POST or GET) is not allowed on the requested resource.
406
Not acceptable
HttpErrorCode.NotAcceptable indicates that the client has indicated with Accept headers that it will not accept any of the available representations of the resource.
407
Proxy authentication required
HttpErrorCode.ProxyAuthenticationRequired indicates that the requested proxy requires authentication. The Proxy-authenticate header contains the details of how to perform the authentication.
408
Request timeout
HttpErrorCode.RequestTimeout indicates that the client did not send a request within the time the server was expecting the request.
409
Conflict
HttpErrorCode.Conflict indicates that the request could not be carried out because of a conflict on the server.
410
Gone
HttpErrorCode.Gone indicates that the requested resource is no longer available.
411
Length required
HttpErrorCode.LengthRequired indicates that the required Content-length header is missing.
412
Precondition failed
HttpErrorCode.PreconditionFailed indicates that a condition set for this request failed, and the request cannot be carried out. Conditions are set with conditional request headers like If-Match, If-None-Match, or If-Unmodified-Since.
413
Request entity too large
HttpErrorCode.RequestEntityTooLarge indicates that the request is too large for the server to process.
414
Request Uri too long
HttpErrorCode.RequestUriTooLong indicates that the URI is too long.
415
Unsupported media type
HttpErrorCode.UnsupportedMediaType indicates that the request is an unsupported type.
416
Requested range not satisfiable
HttpErrorCode.RequestedRangeNotSatisfiable 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.
417
Expectation failed
HttpErrorCode.ExpectationFailed indicates that an expectation given in an Expect header could not be met by the server.
426
Upgrade required
HttpErrorCode.UpgradeRequired indicates that the client should switch to a different protocol such as TLS/1.0.
500
Internal server error
HttpErrorCode.InternalServerError indicates that a generic error has occurred on the server.
501
Not implemented
HttpErrorCode.NotImplemented indicates that the server does not support the requested function.
502
Bad gateway
HttpErrorCode.BadGateway indicates that an intermediate proxy server received a bad response from another proxy or the origin server.
503
Service unavailable
HttpErrorCode.ServiceUnavailable indicates that the server is temporarily unavailable, usually due to high load or maintenance.
504
Gatewaytimeout
HttpErrorCode.GatewayTimeout indicates that an intermediate proxy server timed out while waiting for a response from another proxy or the origin server.
505
HTTP version not supported
HttpErrorCode.HttpVersionNotSupported indicates that the requested HTTP version is not supported by the server.

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.

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:

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:

    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.

Additional resources

External links

Increase your Sitefinity skills by signing up for our free trainings. Get Sitefinity-certified at Progress Education Community to boost your credentials.

Get started with Integration Hub | Sitefinity Cloud | Sitefinity SaaS

This free lesson teaches administrators, marketers, and other business professionals how to use the Integration hub service to create automated workflows between Sitefinity and other business systems.

Web Security for Sitefinity Administrators

This free lesson teaches administrators the basics about protecting yor Sitefinity instance and its sites from external threats. Configure HTTPS, SSL, allow lists for trusted sites, and cookie security, among others.

Foundations of Sitefinity ASP.NET Core Development

The free on-demand video course teaches developers how to use Sitefinity .NET Core and leverage its decoupled architecture and new way of coding against the platform.

Was this article helpful?

Next article

Geo location settings