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:
- In Sitefinity CMS backend, navigate to Administration » Settings » Advanced.
- In the left tree, expand Pages and click Custom error pages.
- 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.
- To disable custom error pages, select Disabled.
The system displays the default ASP.NET error pages to all users – the YSOD.
- 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.
- In Sitefinity CMS backend, navigate to Administration » Settings » Advanced.
- In the left tree, expand Pages » Custom error pages and click Error types » Create new.
- 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.
- 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.
- 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
- 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.
- 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:
- Make sure custom error pages are enabled.
- Navigate to Administration » Settings » Advanced » Pages » Custom error pages » Error types » Create new.
- In HTTP status code, enter 403
- In Error page URL name, enter forbidden-403
- Save your changes.
- Navigate to Pages.
- Create a page with title Forbidden 403 and URL – ~/forbidden-403.
- 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:
- Open the web.config file that is in your project’s folder.
- Find the
<system.webServer> config section
- 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:
- Find the
<system.web> config section in your web.config file
- 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.
- Save and close the web.config file.