Custom error pages
Learn how to implement custom error pages for your AEM as a Cloud Service hosted website.
In this tutorial, you learn:
-
Default error pages
-
From where error pages are served
- AEM service type - author, publish, preview
- Adobe-managed CDN
-
Options to customize error pages
- ErrorDocument Apache directive
- ACS AEM Commons - Error Page Handler
- CDN Error Pages
Default error pages
Let’s review when error pages are displayed, default error pages, and where they are served from.
Error pages are displayed when:
- page does not exist (404)
- not authorized to access a page (403)
- server error (500) because of code issues or server is unreachable.
AEM as a Cloud Service provides default error pages for the above scenarios. It is a generic page and does not match your brand.
The default error page gets served from the AEM service type(author, publish, preview) or from the Adobe-managed CDN. See the table below for more details.
x-aem-error-pass: true
header is set.x-aem-error-pass: true
.This works only for responses coming from AEM or the Apache/Dispatcher layer. Other unexpected errors coming from intermediate infrastructure layers still display the generic error page.
For example, the default error pages served from the AEM service type and Adobe-managed CDN are as follows:
However, you can customize both AEM service type and Adobe-managed CDN error pages to match your brand and provide a better user experience.
Options to customize error pages
The following options are available to customize error pages:
Prerequisites
In this tutorial, you learn how to customize error pages using the ErrorDocument directive, the ACS AEM Commons Error Page Handler and the CDN Error Pages options. To follow this tutorial, you need:
-
The local AEM development environment or AEM as a Cloud Service environment. The CDN Error Pages option is applicable to the AEM as a Cloud Service environment.
-
The AEM WKND project to customize error pages.
Set-up
-
Clone and deploy the AEM WKND project to your local AEM development environment by following the steps below:
code language-none # For local AEM development environment $ git clone git@github.com:adobe/aem-guides-wknd.git $ cd aem-guides-wknd $ mvn clean install -PautoInstallSinglePackage -PautoInstallSinglePackagePublish
-
For AEM as a Cloud Service environment, deploy the AEM WKND project by running the Full-stack pipeline, see the non-production pipeline example.
-
Verify that the WKND site pages render correctly.
ErrorDocument Apache directive to customize AEM served error pages errordocument
To customize AEM served error pages, use the ErrorDocument
Apache directive.
In AEM as a Cloud Service, the ErrorDocument
Apache directive option is only applicable to the publish and preview service types. It is not applicable to the author service type as Apache + Dispatcher is not part of the deployment architecture.
Let’s review how the AEM WKND project uses the ErrorDocument
Apache directive to display custom error pages.
-
The
ui.content.sample
module contains the branded error pages @/content/wknd/language-masters/en/errors
. Review them in your local AEM or AEM as a Cloud Servicehttps://author-p<ID>-e<ID>.adobeaemcloud.com/ui#/aem/sites.html/content/wknd/language-masters/en/errors
environment. -
The
wknd.vhost
file from thedispatcher
module contains:- The ErrorDocument directive that points to the above error pages.
- The DispatcherPassError value is set to 1 so the Dispatcher let Apache handle all errors.
code language-none # In `wknd.vhost` file: ... ## ErrorDocument directive ErrorDocument 404 ${404_PAGE} ErrorDocument 500 ${500_PAGE} ErrorDocument 502 ${500_PAGE} ErrorDocument 503 ${500_PAGE} ErrorDocument 504 ${500_PAGE} ## Add Header for 5XX error page response <IfModule mod_headers.c> ### By default, CDN overrides 5XX error pages. To allow the actual response of the backend to pass through, add the header x-aem-error-pass: true Header set x-aem-error-pass "true" "expr=%{REQUEST_STATUS} >= 500 && %{REQUEST_STATUS} < 600" </IfModule> ... ## DispatcherPassError directive <IfModule disp_apache2.c> ... DispatcherPassError 1 </IfModule> # In `custom.vars` file ... ## Define the error page paths Define 404_PAGE /content/wknd/us/en/errors/404.html Define 500_PAGE /content/wknd/us/en/errors/500.html ...
-
Review the WKND site’s custom error pages by entering an incorrect page name or path in your environment, for example https://publish-p105881-e991000.adobeaemcloud.com/us/en/foo/bar.html.
ACS AEM Commons-Error Page Handler to customize AEM served error pages acs-aem-commons
To customize AEM served error pages across all AEM service types, you can use the ACS AEM Commons Error Page Handler option.
. For detailed step-by-step instructions, see the How to Use section.
CDN error pages to customize CDN served error pages cdn-error-pages
To customize error pages served by the Adobe-managed CDN, use the CDN error pages option.
Let’s implement CDN error pages to customize error pages when the Adobe-managed CDN cannot reach the AEM service type (origin server).
The high-level steps to implement CDN error pages are:
- Develop a custom error page content as a Single Page Application (SPA).
- Host the static files required for the CDN error page in a publicly accessible location.
- Configure the CDN rule (errorPages) and reference the above static files.
- Deploy the configured CDN rule to the AEM as a Cloud Service environment using the Cloud Manager pipeline.
- Test the CDN error pages.
CDN error pages overview
The CDN error page is implemented as a Single Page Application (SPA) by the Adobe-managed CDN. The SPA HTML document delivered by the Adobe-managed CDN contains the bare minimum HTML snippet. The custom error page content is generated dynamically using a JavaScript file. The JavaScript file must be developed and hosted in a publicly accessible location by the customer.
The HTML snippet delivered by the Adobe-managed CDN has the following structure:
<!DOCTYPE html>
<html lang="en">
<head>
...
<title>{title}</title>
<link rel="icon" href="{icoUrl}">
<link rel="stylesheet" href="{cssUrl}">
</head>
<body>
<script src="{jsUrl}"></script>
</body>
</html>
The HTML snippet contains the following placeholders:
- jsUrl: The absolute URL of the JavaScript file to render the error page content by creating HTML elements dynamically.
- cssUrl: The absolute URL of the CSS file to style the error page content.
- icoUrl: The absolute URL of the favicon.
Develop a custom error page
Let’s develop the WKND specific branded error page content as a Single Page Application (SPA).
For demo purposes, let’s use React, however, you can use any JavaScript framework or library.
-
Create a new React project by running the following command:
code language-none $ npx create-react-app aem-cdn-error-page
-
Open the project in your favorite code editor and update the below files:
-
src/App.js
: It is the main component that renders the error page content.code language-javascript import logo from "./wknd-logo.png"; import "./App.css"; function App() { return ( <> <div className="App"> <div className="container"> <img src={logo} className="App-logo" alt="logo" /> </div> </div> <div className="container"> <div className="error-code">CDN Error Page</div> <h1 className="error-message">Ruh-Roh! Page Not Found</h1> <p className="error-description"> We're sorry, we are unable to fetch this page! </p> </div> </> ); } export default App;
-
src/App.css
: Style the error page content.code language-css .App { text-align: left; } .App-logo { height: 14vmin; pointer-events: none; } body { margin-top: 0; padding: 0; font-family: Arial, sans-serif; background-color: #fff; color: #333; display: flex; justify-content: center; align-items: center; } .container { text-align: letf; padding-top: 10px; } .error-code { font-size: 4rem; font-weight: bold; color: #ff6b6b; } .error-message { font-size: 2.5rem; margin-bottom: 10px; } .error-description { font-size: 1rem; margin-bottom: 20px; }
-
Add the
wknd-logo.png
file to thesrc
folder. Copy the file aswknd-logo.png
. -
Add the
favicon.ico
file to thepublic
folder. Copy the file asfavicon.ico
. -
Verify the WKND branded CDN error page content by running the project:
code language-none $ npm start
Open the browser and navigate to
http://localhost:3000/
to see the CDN error page content. -
Build the project to generate the static files:
code language-none $ npm run build
The static files are generated in the
build
folder.
-
Alternatively, you can download the aem-cdn-error-page.zip file containing the above React project files.
Next, host the above static files in a publicly accessible location.
Host static files required for CDN error page
Let’s host the static files in Azure Blob Storage. However, you can use any static file hosting service like Netlify, Vercel, or AWS S3.
-
Follow the official Azure Blob Storage documentation to create a container and upload the static files.
note important IMPORTANT If you are using other static file hosting services, follow their documentation to host the static files. -
Make sure that the static files are publicly accessible. My WKND demo specific storage account settings are as follows:
- Storage Account Name:
aemcdnerrorpageresources
- Container Name:
static-files
- Storage Account Name:
-
In above
static-files
container, below files from thebuild
folder are uploaded:error.js
: Thebuild/static/js/main.<hash>.js
file is renamed toerror.js
and publicly accessible.error.css
: Thebuild/static/css/main.<hash>.css
file is renamed toerror.css
and publicly accessible.favicon.ico
: Thebuild/favicon.ico
file is uploaded as is and publicly accessible.
Next, configure the CDN rule (errorPages) and reference the above static files.
Configure the CDN rule
Let’s configure the errorPages
CDN rule that uses the above static files to render the CDN error page content.
-
Open the
cdn.yaml
file from the mainconfig
folder of your AEM project. For example, the WKND project’s cdn.yaml file. -
Add the following CDN rule to the
cdn.yaml
file:code language-yaml kind: "CDN" version: "1" metadata: envTypes: ["dev", "stage", "prod"] data: # The CDN Error Page configuration. # The error page is displayed when the Adobe-managed CDN is unable to reach the origin server. # It is implemented as a Single Page Application (SPA) and WKND branded content must be generated dynamically using the JavaScript file errorPages: spa: title: Adobe AEM CDN Error Page # The title of the error page icoUrl: https://aemcdnerrorpageresources.blob.core.windows.net/static-files/favicon.ico # The PUBLIC URL of the favicon cssUrl: https://aemcdnerrorpageresources.blob.core.windows.net/static-files/error.css # The PUBLIC URL of the CSS file jsUrl: https://aemcdnerrorpageresources.blob.core.windows.net/static-files/error.js # The PUBLIC URL of the JavaScript file
-
Save, commit, and push the changes to the Adobe upstream repository.
Deploy the CDN rule
Finally, deploy the configured CDN rule to the AEM as a Cloud Service environment using the Cloud Manager pipeline.
-
In the Cloud Manager, navigate to the Pipelines section.
-
Create a new pipeline or select the existing pipeline that deploys only the Config files. For detailed steps, see Create a config pipeline.
-
Click the Run button to deploy the CDN rule.
Test the CDN error pages
To test the CDN error pages, follow the below steps:
-
In the browser, navigate to the AEM as a Cloud Service’s Publish URL, append the
cdnstatus?code=404
to the URL, for example, https://publish-p105881-e991000.adobeaemcloud.com/cdnstatus?code=404 or access using the custom domain URL -
The supported codes are: 403, 404, 406, 500 and 503.
-
Verify the browser network tab to see the static files are loaded from the Azure Blob Storage. The HTML document delivered by the Adobe-managed CDN contains the bare minimum content and the JavaScript file dynamically creates the branded error page content.
Summary
In this tutorial, you learned about default error pages, where error pages are served from, and options to customize error pages. You learned how to implement custom error pages using the ErrorDocument
Apache directive, the ACS AEM Commons Error Page Handler
, and the CDN Error Pages
options.