Error Page Handler
Available since version 1.0.0
New in version 1.6.0 the ACS AEM Commons Error Page Handler comes w a light in-memory TTL-based caching layer to greatly enhance performance.
Provide an author-able means for defining, creating and managing custom Error pages per content tree/site.
Author is displayed the corresponding error page
Normal/OOTB 500x/Exception error handling behavior is respected. JSP exceptions are displayed inline w the JSP.
Author is displayed the corresponding Error page
A custom “Error page” is displayed that includes the Request Progress and Stack Trace.
Disabled (Publish) mode
The corresponding Error page is displayed.
How to Use
In AEM Dispatcher configuration, set
DispatcherPassErrorto ‘0’. This allows erring requests to be sent back to AEM.
- Create the proxy overlays for Sling errorhandler scripts (404.jsp and default.jsp) which include the acs-commons counterparts.
Create the overlay for 404.jsp
Then create the overlay for the default.jsp
- In your base page implementation, add the following
cq:Widgetto the Page Properties dialog
OR create a your own custom pathfield widget
Create a sling:OsgiConfig node to enable the Error Page Handler
Note: ttl is the TTL of the in-memory error page cache in seconds
- Create a CQ Page that will act as the default Error page, and also contain all custom variations of error pages.
Each error page’s “name” (Node name) should correspond to the HTTP Response Status code it should respond to.
- 500: Internal Server Error
- 404: Not Found
- 403: Forbidden
Typically only 404 and 500 are needed with everything else using the fallback (default error page) as the messaging around these tends to be less useful to Web site visitors. A common pattern is to create this at the site’s root under a node named “errors”
- Ex. /content/geometrixx/en/errors
Create any error-specific pages under this default error page created in Step 2. Note, it is critical that the page NAMES (node names) follow status codes. The Page Titles can be anything.
- Ex. /content/geometrixx/en/errors/404
- Ex. /content/geometrixx/en/errors/500
Edit the Page Properties of the site’s root node, and in the new “Error Pages” dialog input (Step 1) select the default error page (Step 2).
- Ex. ./errorPages => /content/geometrixx/en/errors
- Further customizations can be made via the OSGi Configuration for the ACS AEM Commons - Error Page Handler Configuration, including a “System wide” fallback error page.
Note: At this time the full Sling exception-name look-up scheme is not supported. Implementing a 500 error page is sufficient.
In Memory TTL-based Cache (Since v1.5.0)
Introduced in ACS AEM Commons 1.5.0, Error Page Handler comes w an in-memory TTL based. It is recommended you upgrade to 1.5.0 and configure the cache per your requirements using the sling:OsgiConfig settings outlined above.
- The cache implementation is an implementation detail and may change over time without notice; This may change the MBean behavior, attributes and operations. *
An ErrorPageHandler MBean is available when the Error Page Handler is enabled. This MBean reports on the In Memory caches entries, size in KB, hit/miss rates. It also provides functionality to clear the cache and to view the contents of the cache.
Error Page Handler Cache overview
Viewing the contents of the cache for a particular entry
Error Images (Since v1.7.0)
Introduced in ACS AEM Commons 1.7.0, Error Page Handler supports serving an “error image” in the event a request with a qualified “image” extension (jpg, jpeg, png and gif) cannot be found. The OSGi config properties described in futher detail below int he Advanced section can be used to configure this feature.
Advanced Sling OSGi Configuration
The Error Page Handler has a few more advanced settings that are typically unused/left as default.
enabledtrue/false to toggle the Error Page Handler on and off
vanity.dispatch.enabledtrue/false to toggle using the ACS Commons Vanity Path Re-writer Mapper. Since v3.10.0.
not-found.behavior = redirect-to-login || respond-with-404Defines the default behavior for 404’ing requests. Defaults to
respond-with-404. (Since v1.9.4)
not-found.exclusion-path-patterns = [ /content/foo/.* ]Defines a list of path patterns (Regex) should respond using the opposite method to
not-found-behavior. Example. If
not-found-behavior=respond-with-404, anonymous requests sent to
/content/site/profile/.*can be sent to the login page, instead of responding with the usual 404. (Since v.1.9.4)
cache.serve-authenticatedtrue allows authenticated requests to service the the in-memory cache. If your error pages do not contain any server-side personalization, this should be set to true to maximize cache effectiveness. (Since v1.5.0)
cache.ttlTTL in seconds for the in-memory Error Page Handler cache; Defaults to 300 seconds (5 mins). (Since v1.5.0)
error-page.system-pathis the absolute path to system Error page resource to serve if no other more appropriate error pages can be found. Does not include extension.
error-page.fallback-namedefines the error page name (not path) to use if a valid Error Code/Error Servlet Name cannot be retrieved from the Request. Defaults to
error-page.extensiondefines the extension to call the fallback error page with; This is almost ALWAYS “html” unless the application is using non-standard extensions.
pathsdefine a list of valid inclusive content trees under which error pages may reside, along with the name of the the default error page for the content tree. This is a fallback/less powerful option to adding the
./errorPagesproperty to CQ Page property dialogs. Examples:
error-images.enabledboolean value; true to enable, false to disable. Defaults to false. (Since version 1.7.0)
error-images.pathis a <selectors.extension> (ex.
.img.png) absolute path to a nt:file image, or relative path to a image component resource.
If an extension or relative path, this value is applied to the resolved error page. (ex. if error-image.path is ‘jcr:content/image.img.png’ and the resolve error path is ‘/content/acme/error’ then ‘/content/acme/error/jcr:content/image.img.png’ will be used to render the image.). Defaults to ‘.img.png’ which will render the error page’s Page image. (Since version 1.7.0)
Note: It is better to use the Page Properties-defined
errorPages than the
paths in the OSGi Configuration. Typically
paths is left blank.
Internationalization on Error Pages
If your error pages require the I18N bundle, you must extend the I18NFilter configuration to include it in ERROR-scoped filter chain.
Create an nt:file node to configure the Sling I18N Filter
Note: You must use a .config file because the
service.ranking must be of type integer, which cannot be set on a sling:OsgiConfig node.
On AEM 6.2 or above, this service uses a Service User for repository access. This user is configured with the expected permissions required, but additional permissions may be required if your repository design deviates from the expected structure.