• Document Up to Date
  • Updated On 4.1.5

Custom Error Pages

When an error in a browser request occurs in your application, what the user sees in their browser, called an error page depends on what has been configured in your application. The most common error pages are client (4xx) and server (5xx) errors, for status code such as:

  • 400 Bad Request - This error appears when the request is invalid

  • 401 Authentication Required - This error indicates lack of authorization credentials

  • 403 Forbidden - This error appears when you don’t have the necessary permissions to access a page

  • 404 Not Found - This error indicates the server couldn’t find the requested page

  • 500 Internal Server Error - This errors appears when the server encountered a problem and could not complete the request

  • 502 Bad Gateway - This error indicates some network connectivity problem

  • 503 Service Unavailable - This error indicates the server is not available for usage due to temporary overloading or a maintenance issue

Default error pages are most of the time unsightly, containing the exception/error details and maybe some stack trace and other information that may be useful to developers but confusing for users.

Custom error pages allows you to handle unexpected situations in your site/application in a user-friendly way. It makes it easier for users who stumble across errors in your site/application to continue their session and get back on track by informing users that something has gone wrong and then provides them with options on how to continue.

CrafterCMS provides default templates for error pages such as 404 Not Found, 403 Forbidden and others, located in CRAFTER_HOME/bin/apache-tomcat/webapps/studio/WEB_INF/templates/web/errors and/or CRAFTER_HOME/bin/apache-tomcat/webapps/ROOT/WEB_INF/templates/web/errors. These default error pages are displayed when no custom error pages have been created for the corresponding error status code in your project.

Below is an example of the default error page displayed by CrafterCMS for a 404 error:

Default CrafterCMS 404 Not Found Error Page

CrafterCMS supports using custom error pages. When Crafter Engine detects an error trying to fulfill a request it will also look for a custom error page to display in the browser. If it doesn’t find a custom error page in the project, it will display the default error page provided by CrafterCMS mentioned above.

To add custom errors page in your project, do the following:

  1. Create a new folder under /templates/web/errors on the Sidebar

  2. Create a Freemarker template using as name the error code for which the page will be displayed, e.g., 404.ftl

In the custom error templates developers are free to include any HTML/CSS/JS to make sure that the page matches the rest of the site.

Note

Custom Error pages are standalone templates, they are not associated with any site item and will not have the model object available.

Note

A valid context is required for custom error pages to render. If Crafter Engine is not able to load your site context due to a configuration or some other error condition, you will receive a default system error page.

Once the file is saved it will be used automatically in preview, for a delivery node you need to publish the new file so that it takes effect in the live site.


Example

Let’s take a look at examples of custom error pages. For this example, we will be using a project created using the Website Editorial blueprint. We’ll look at the custom error page for 404 Not Found status code provided in the Website Editorial blueprint, and then create a custom error page for 403 Forbidden status code.

The Website Editorial blueprint provides example custom error pages for 404 and 500, so we don’t need to create the folder templates/web/errors/. Open the Sidebar and navigate to templates/web/errors/. Let’s take a look at the 404 custom error page by clicking on 404.ftl then clicking on Edit.

Sample "404.ftl"
CRAFTER_HOME/data/repos/sites/SITENAME/sandbox//sandbox/templates/web/errors/404.ftl
 1<html lang="en">
 2	<head>
 3		<title>Editorial</title>
 4		<meta charset="utf-8" />
 5		<meta name="viewport" content="width=device-width, initial-scale=1, user-scalable=no" />
 6		<!--[if lte IE 8]><script src="/static-assets/js/ie/html5shiv.js"></script><![endif]-->
 7		<link rel="stylesheet" href="/static-assets/css/main.css" />
 8		<!--[if lte IE 9]><link rel="stylesheet" href="/static-assets/css/ie9.css" /><![endif]-->
 9		<!--[if lte IE 8]><link rel="stylesheet" href="/static-assets/css/ie8.css" /><![endif]-->
10		<link rel="stylesheet" href="/static-assets/css/jquery-ui.min.css" />
11	</head>
12	<body>
13    	<!-- Wrapper -->
14			<div id="wrapper">
15
16				<!-- Main -->
17					<div id="main">
18						<div class="inner">
19
20                            <!-- Header -->
21							<@renderComponent componentPath="/site/components/headers/header.xml" />
22
23                            <!-- Banner -->
24								<section id="banner">
25									<div class="content">
26										<header><h1>The page you are looking for doesn't exist.</h1></header>
27										Go back <a href="/">home</a>
28									</div>
29								</section>
30                        </div>
31                    </div>
32             </div>
33             <!-- Scripts -->
34			<script src="/static-assets/js/jquery.min.js"></script>
35			<script src="/static-assets/js/jquery-ui.min.js"></script>
36			<script src="/static-assets/js/skel.min.js"></script>
37			<script src="/static-assets/js/util.js"></script>
38			<!--[if lte IE 8]><script src="/static-assets/js/ie/respond.min.js"></script><![endif]-->
39			<script src="/static-assets/js/main.js"></script>
40    </body>
41</html>

Notice that in the template file above, the header used for the Website Editorial is used in the page, to give the custom error page a cohesive look with the site. Below is how the above custom error page looks like:

Website Editorial Custom Error Page 404 Not Found

Default Website Editorial blueprint custom error page.


Next, let’s create a custom error page for 403 Forbidden status code. In the Sidebar, navigate to /templates/web/errors then right click on it. Select New Template, then type in 403.ftl as the File Name. We can copy the contents of the 404.ftl file, and modify it for the 403 status code by adding an image and text to let the user know that the page they’re trying to reach is forbidden.

403.ftl
 1...
 2<!-- Header -->
 3    <@renderComponent componentPath="/site/components/headers/header.xml" />
 4
 5<div style="text-align: center">
 6  <br/>
 7  <img src="/static-assets/images/no-entry.jpg" alt="No entry sign" style="width: 55vw; min-width: 330px;display: block; margin-left: auto; margin-right: auto;"/>
 8  <br/>
 9  <header><h1>Sorry!</h1></header>
10  This area is forbidden. Go back <a href="/">home</a> now
11</div>
12...

Below is how the above 403 Forbidden custom error page looks like:

Website Editorial 403 Forbidden Custom Error Page

Custom 403 Forbidden error page.

Remember to publish the new 403.ftl file so that it takes effect in the live site.