CMS, Managed Services, Uncategorized

Error handling using a dispatcher

Error handling using a Dispatcher

In a normal scenario, AEM uses the Sling’s default error page for handling the errors.

In other scenarios like creating an overlay etc. to display a branded/customized error page and not the default one, below steps describe the process flow,

  • A user requests for a page (eg. /xyz/abc/pq.html)
  • Dispatcher looks out for it, in its cache.
  • If not found in cache, it will ask Publish if it has the resource
  • Publish returns the customized 404.
  • Dispatcher will not cache any error documents.
  • Apache sends the user the customized 404 at the original request path.


This creates several problems. One of them could be a DDOS.


So, the solution to this problem can be obtained by following the below flow,

  • A user requests for a page.
  • Dispatcher looks for it in cache and when it does not find it there, it checks in Publish.
  • Publish also doesn’t have the page that is being requested.
  • Publish then serves the default Sling error page which is not attractive.
  • Dispatcher identifies the error, doesn’t cache, but let’s Apache handle the request with the ErrorDocument directive.
  • After this, Dispatcher makes another Publish request based on the ErrorDocument path.
  • Publish then send the customized 404 error page with a 200 status.
  • Dispatcher caches the new 404 page.
  • Apache delivers our 404 content at the original location (with the correct 404 status code).


To achieve this, configurations have to be made at AEM, Dispatcher and web server level.

Below are the configurations needed to achieve error handling via Dispatcher.


Create a 404 page with the necessary components, text etc. as per your requirement and place it in the /content/site path.


We then have to tell the Dispatcher to pass the error to Apache.

This can be done by adding the below line in the dispatcher.conf file or httpd.conf file depending upon how you configured your dispatcher.

DispatcherPassError 1


We then have to define the ErrorDocument directive in APache which tells it about where the error page is (OR) what should be displayed upon receiving an error.
The syntax of the ErrorDocument directive is:

ErrorDocument <3-digit-code> <action>

where the action will be treated as:

1.A local URL to redirect to (if the action begins with a “/”).
2.An external URL to redirect to (if the action is a valid URL).
3.Text to be displayed (if none of the above). The text must be wrapped in quotes (“) if it consists of more than one word.

For example, if you have the error page in /content/site1 location then the ErrorDocument in this site’s vhost file can be given as:

ErrorDocument 404 /content/site1/404.html

ErrorDocument 500 /content/site1/500.html

(OR) specify the URL to which the error page should land to,

ErrorDocument 500

(OR) specify the text to be displayed when an error occurs,

ErrorDocument 500 “Sorry, our script crashed. Oh dear”

Note: It is always good to only specify the error codes for which you have the HTML content.

After configuring these 3 (AEM, Dispatcher and Apache)steps, the customized pages from AEM will be shown for 404 and 500 errors(for the above example).

About The Author

Leave a Reply