Custom error pages

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

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.

Clone and deploy the AEM WKND project to your local AEM development environment by following the steps below:

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

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 Service https://author-p<ID>-e<ID>.adobeaemcloud.com/ui#/aem/sites.html/content/wknd/language-masters/en/errors environment.

The wknd.vhost file from the dispatcher 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.

...
# ErrorDocument directive in wknd.vhost file
ErrorDocument 404 ${404_PAGE}
ErrorDocument 500 ${500_PAGE}
ErrorDocument 502 ${500_PAGE}
ErrorDocument 503 ${500_PAGE}
ErrorDocument 504 ${500_PAGE}

...
# DispatcherPassError value in wknd.vhost file
<IfModule disp_apache2.c>
    ...
    DispatcherPassError        1
</IfModule>

# Custom error pages path in custom.vars file
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.

Create a new React project by running the following command:

$ 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 the src folder. Copy the file as wknd-logo.png.

• Add the favicon.ico file to the public folder. Copy the file as favicon.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.

Follow the official Azure Blob Storage documentation to create a container and upload 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

In above static-files container, below files from the build folder are uploaded:

• error.js: The build/static/js/main.<hash>.js file is renamed to error.js and publicly accessible.
• error.css: The build/static/css/main.<hash>.css file is renamed to error.css and publicly accessible.
• favicon.ico: The build/favicon.ico file is uploaded as is and publicly accessible.

Open the browser and navigate to the Publish environment 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.

Configuring CDN Error Pages

Cloud Manager - Config pipelines