Note: This guide describes Kentico CMS version 7. Unfortunately, we cannot support this guide from version 8 forward. Go to latest documentation

Skip to end of metadata
Go to start of metadata

You can configure the system to display custom pages instead of standard error messages. Custom pages help reduce the inconvenience caused to visitors if they run into an error while browsing your website, and also improves the security of the site by hiding potentially sensitive internal data (such as code in stack traces). You can create custom pages for this purpose with any kind of content, such as an apology or additional instructions, and then configure the system to display the pages in the appropriate situations.

Adding custom Page not found error pages

The Page not found error (404 HTTP status code) is one of the most common problems encountered by visitors. Kentico CMS provides several features that allow you to conveniently set up a custom page as a response. For page not found errors, the error page can either be a physical .aspx file placed under the web project or a dedicated document created in a specific website's content tree.

To assign your custom page to a particular website (or globally):

  1. Go to Site Manager-> Settings -> Content.
  2. Enter the URL of the given page as the value of the Page not found URL setting, for example: ~/SpecialPages/PageNotFound.aspx

    Since there are two possible types of error pages, the system interprets the URL in two different ways. The sample URL value above specifies either:

    • The URL of a physical page named PageNotFound.aspx located in the web project under a folder called SpecialPages.
    • If such a file does not exist, the system attempts to select a Kentico CMS document under the current website, with an alias path equal to /SpecialPages/PageNotFound.
  3. Click  Save.

It is recommended to use Kentico CMS documents for page not found error pages. With this approach, you can define the error page's content using the portal engine and leverage all of its features. For instance, you can translate the page not found document on a multilingual website and the CMS automatically displays the culture version that matches the language selected by the user.

You do not need to manually handle the HTTP response code of the page specified by the setting. The page automatically returns a 404 status code when accessed (applies to both documents and physical pages). This allows applications, services and web crawlers to find out that a page not found error has occurred.

Setting a custom Page not found page


Handling 404 errors for general content

To ensure that the system returns your custom Page not found error page for invalid requests that target all types of site content, not just the pages processed by the Kentico CMS engine, you need to fulfill several additional requirements.

  • The site must be hosted on IIS version 7 or newer.
  • The Managed pipeline mode of the application pool needs to be set to Integrated.

If your environment meets the conditions above:

  1. Edit your application's web.config file.
  2. Find the system.webServer section directly under the root (i.e. not under a specific <location> element).
  3. Add the following attribute to the section's <modules> element:
<modules runAllManagedModulesForAllRequests="true">


On this page

Handling general errors

Kentico CMS is a standard ASP.NET application, so you can configure the handling of all types of errors and exceptions by adding the <httpErrors> element into the <system.webServer> section of your web.config file:

	<httpErrors existingResponse="Auto" errorMode="Custom">
		<clear />
		<error statusCode="500" path="/<Virtual_Directory>/CMSMessages/CustomError.aspx" responseMode="ExecuteURL" />

The errorMode attribute sets the basic error page behavior. Use one of the following options:

  • Detailed - in this mode, the default error pages display details of the encountered error to all users.
  • DetailedLocalOnly - with this option, the default error pages show detailed error information only to the local host. Users who access the site remotely see simplified error pages.
  • Custom - use this mode if you wish to replace the default error pages with a completely custom page.

When specifying custom error pages:

  1. Set the errorMode to Custom.
  2. Add any number of child <error> elements representing individual types of HTTP errors that you wish to handle.
    • You need to enter the HTTP response code of the given error into the statusCode attribute and the URL of the appropriate error page as the path value.
    • If your Kentico CMS application is running in a virtual directory, replace the <Virtual_Directory> string in the sample path value above with the directory's name.
    • It is recommended to add general error pages directly into your web project as .aspx files, e.g. under the CMSMessages folder. For pages placed in your web project, set the responseMode attribute of the corresponding <error> elements to ExecuteURL.
    • You can define the content of the error page to match your specific requirements.
    • Keep in mind that error pages should always return the appropriate HTTPResponse status code.

Before the deployment

Do not forget to set custom error messages as described in this procedure before deploying your website and going live. Also, remember to disable debugging and tracing for your ASP.NET application. See Web.config file settings.

Note: The approach described above works for applications running on IIS 7 or newer with an application pool using Integrated Managed pipeline mode. On older versions, you can instead edit the <customErrors> element under the <system.web> section of the web.config to achieve similar results.