Customizing Pages shown by the Error Handler

CQ comes with a standard error handler for handling HTTP errors; for example, by showing:

System provided scripts exist (under /libs/sling/servlet/errorhandler) to respond to error codes, by default the following are available with a standard CQ instance:

403.jsp
404.jsp

Note

CQ is based on Apache Sling, so see http://sling.apache.org/site/errorhandling.html for detailed information about Sling Error Handling.

Note

On an author instance, CQ WCM Debug Filter is enabled by default. This always results in the response code 200. The default error handler responds by writing the full stack trace to the response.

On a publish instance, CQ WCM Debug Filter is always disabled (even if configured as enabled).

How to Customize Pages shown by the Error Handler

You can develop your own scripts to customize the pages shown by the error handler when an error is encountered. Your customized pages will be created under /apps and overlay the default pages (that are under /libs).

In the repository, copy the default script(s):

from /libs/sling/servlet/errorhandler/
to /apps/sling/servlet/errorhandler/

As the destination path does not exist by default you will need to create it when doing this for the first time.

Navigate to /apps/sling/servlet/errorhandler. Here you can either:

edit the appropriate existing script to supply the information required.
create, and edit, a new script for the required code.

Save the changes and test.

Caution

The 404.jsp and 403.jsp handlers have been specifically designed to cater for CQ5 authentication; in particular, to allow for system login in the case of these errors.

Therefore, replacement of these two handlers should be done with great care.

Customizing the Response to HTTP 500 Errors

HTTP 500 errors are caused by server side exceptions.

500 Internal Server Error
The server encountered an unexpected condition which prevented it from fulfilling the request.

When request processing results in an exception, the Apache Sling framework (that CQ is built on):

logs the exception
returns:
- the HTTP response code 500
- the exception stack trace
in the body of the response.

By customizing the pages shown by the error handler a 500.jsp script can be created. However, it is only used if HttpServletResponse.sendError(500) is executed explicitly; i.e. from an exception catcher.

Otherwise, the response code is set to 500, but the 500.jsp script is not executed.

To handle 500 errors, the file name of the error handler script must be the same as the exception class (or superclass). To handle all such exceptions you can create a script /apps/sling/servlet/errorhandler/Throwable.jsp or /apps/sling/servlet/errorhandler/Exception.jsp.

Caution

On an author instance, CQ WCM Debug Filter is enabled by default. This always results in the response code 200. The default error handler responds by writing the full stack trace to the response.

For a custom error-handler, responses with code 500 are needed - so the CQ WCM Debug Filter needs to be disabled. This ensures that the response code 500 is returned, which in turn triggers the correct Sling error-handler.

On a publish instance, CQ WCM Debug Filter is always disabled (even if configured as enabled).

Your comments are welcome.

Did you notice a way we could improve the documentation on this page? Is something unclear or insufficiently explained? Please leave your comments below and we will make the appropriate changes. Comments that have been addressed, by improving the documentation accordingly, will then be removed.

COMMENTS

By Damon - 6:58 PM on Mar 12, 2012 Reply
For Throwable.jsp and Exception.jsp how do you get access to the exception within these scripts? Is there a tag that needs to be defined?
By Indrajeet - 1:04 PM on Mar 14, 2012 Reply
I have the same question as Damon,
can we have some sample of Exception.jsp?
Please reply.

Thanks in advance.
By Andy Green - 5:38 AM on May 10, 2012 Reply
Hi

In CQ, when a restricted content is accessed it returns HTTP status code 404 instead of 403. Please advice how to change this behavior

Thanks

ADD A COMMENT

In order to post a comment, you need to sign-in.

Note: Customers with DayCare user accounts need to create a new account for use on day.com.