Creating AEM error pages for custom 404 and 500 handlers in Sling
A missing page and a failed page may both end on a polished screen, but they represent different system conditions. A custom AEM error page should preserve the correct HTTP status, give visitors a useful route onward and avoid disguising a server fault as ordinary browsing. Apache Sling provides the request and response mechanisms used to render that experience inside Adobe Experience Manager.
For a 404 response, Sling cannot resolve the requested path to a publish resource. A 500 response means an unhandled exception interrupted processing. The distinction matters to browsers, search engines, monitoring tools and any content delivery network in front of AEM, so matching the visual design is only part of a reliable error-handling strategy.
CIRCUIT’s two-day Chicago conference gathered Java developers, AEM architects, front-end engineers and systems specialists around closely related implementation concerns. Its 2015 and 2016 recordings remain a useful record of AEM integrations, architecture and developer workflows, while this pattern turns those broader themes into a concrete Sling implementation.
Trace the failure through the delivery stack
Before choosing a file, reproduce the failure at every delivery layer. Start with the public URL and note whether the request reaches AEM publish, whether the dispatcher or CDN creates the response, and whether an authentication layer intervenes. A 404 can mean missing content, a broken rewrite or an expired campaign URL. A 500 can originate in resource resolution, a servlet, a backend or a template. If an edge layer answers first, the AEM error page never appears.
Record the status, body and cache headers for the exact request. A branded body returned with a 200 masks a broken link and corrupts monitoring. Conversely, a CDN fallback can show a generic page while the origin never receives the request. This chain identifies whether the fix belongs in content, routing, dispatcher rules or the Sling error handler.
Design recovery and incident response separately
A custom 404 page should help people continue their task. Offer search, popular destinations, store or service information and clearly labelled links rather than a dead-end apology. A custom 500 page has a different job: acknowledge the temporary problem, provide a support route and display a reference if one exists. It must never expose a stack trace, servlet name or internal hostname.
The two experiences can share HTL components, typography and accessibility patterns without sharing misleading content. Keep the 500 template deliberately static because the dependency that triggered the exception may also prevent navigation or search from working. Add analytics events that identify the status and page variant, but exclude personal data and avoid sending the full broken URL as a campaign keyword.
Create status-specific AEM resources
In common AEM 6.5 deployments, the status-specific resources are usually /apps/<site>/errorpages/404.html and /apps/<site>/errorpages/500.html. Treat that convention as a deployment setting rather than a universal promise. AEM as a Cloud Service and some product releases expose error-page configuration through the site interface, while Sling mappings can differ. Confirm the resolved path against the publish tier before promoting templates.
Create each file as valid HTL, formerly called Sightly, or as an HTML content resource that includes a shared design component. Keep the 404 page able to use catalogue search and global navigation. Limit the 500 page to content that can be delivered independently of the failing service. Apply least-privilege permissions to the error path and test it anonymously because public traffic will not carry author credentials.
Configure Sling to preserve HTTP semantics
Let Sling’s standard error servlet resolve the status-specific resource whenever the built-in AEM mechanism meets the project’s requirements. A dedicated Sling servlet is justified when the response needs behaviour that cannot be expressed in a template, such as generating a signed incident token. Scope that servlet to the intended resource type and selector, then verify that it resolves only for error requests.
Within the handler, read the status supplied by Sling through the supported request attribute and set the response status before writing or committing the body. Follow the API for the deployed Sling version rather than copying an attribute name between projects. Never redirect an error to a branded page because the browser would receive a redirect status instead of the original 404 or 500. Sanitise any echoed path and exception text, and keep detailed diagnostics in protected logs.
Localise the experience for Australian visitors
For an Australian audience, a useful 404 may offer store or service links for Sydney, Melbourne and Brisbane, plus a route to Australian customer support. Use the en-AU locale, Australian English, AU$ pricing and GST-inclusive wording rather than inherited US copy. Date formats, opening hours and campaign references should follow Australian conventions. Around daylight-saving changes, a single hard-coded offset will mislead visitors because Brisbane observes a different schedule from Sydney and Melbourne.
CIRCUIT’s coverage of automated language-copy workflows shows how localisation can be built into the content lifecycle rather than left as a final translation sweep. Extend that discipline to error experiences: route each language to the correct regional fallback, maintain the same HTTP status and have editors review legal, support and currency language before publication. Search results should respect the visitor’s selected locale rather than returning an unrelated English page.
Align the dispatcher, CDN and security controls
The ICF Olson profile from CIRCUIT provides useful conference context for an architecture-led approach to AEM delivery. Trace a request through the CDN, dispatcher, publish tier and any microservice before deciding where the custom error handler belongs. One layer may rewrite a URL or expose a generic response before Sling can evaluate it. Keep the origin status visible in logs so teams can distinguish content gaps from delivery failures.
At the dispatcher, verify that the error resource is reachable anonymously and that an ErrorDocument or fallback rule does not replace the original status. At the CDN, cache a 404 only briefly and prevent long-lived caching of a 500. If the edge supplies a fallback page, it is a last resort rather than a replacement for the Sling response. Exclude stack traces, upstream headers and sensitive server details from fallback content and logs.
Test, observe and complete the implementation
Test the contract as well as the design. A missing unpublished path must return 404, a deliberately raised publish exception must return 500, and both responses must contain the intended content markers and the correct content type. Add checks for cache headers, language selection, redirect behaviour and the absence of exception details. Run the same suite directly against publish, through the dispatcher and through the CDN because each layer can change what the browser receives.
Internal operational views deserve the same attention. The event post on workflow dashboard customisation demonstrates how tailored workflow information can help teams act quickly. Keep those views separate from public 500 pages, where an incident ID can link to a status page but not expose internal actions. Monitor aggregated 404 trends by template and campaign, and alert on 500 rate, latency and error distribution across Australian regions.
Start with one controlled missing URL and one isolated exception, then turn the results into an implementation ticket covering Sling resolution, HTTP status, localisation, caching, security and accessibility. Reuse the CIRCUIT recordings and linked technical material to align developers, architects and operations, and promote the first templates only after they pass publish, dispatcher and CDN checks.