Custom Error Pages Dispatcher AEM as Cloude Service PassThrough not working

[sai_charanAr]

Current Implementation:

We have previously implemented custom error page handling using ACS AEM Commons Error Page Handler in AMS. Now, we are migrating the code to AEM as a Cloud Service. We have implemented the same approach by adding a folder under ui.apps:

/apps/acs-commons/components/utilities/errorpagehandler/404.jsp

This folder contains all the custom error pages related to the project. Additionally, we created another folder at:

/apps/sling/servlet/errorhandler/default.jsp

This folder refers to the ACS Commons path. The configuration works, and we are getting custom 404 pages. However, when we deploy the code and try to access other ACS Commons lists through AEM sites, those pages are blocked because /apps/acs-commons is overriding the path. We tried a different approach using ErrorDocument directives through the dispatcher, which also works by redirecting to the custom 404 page mentioned in the ErrorDocument directive. The issue is that it should not show in the URL; it should redirect internally like a passthrough.

Example:

If we hit www.example.com/sites/page1.html and this page does not exist, it should maintain the same URL in the browser but internally redirect to the 404 page.

What We Have Tried:

We used the following header:

Header set x-aem-error-pass "true" "expr=%{REQUEST_STATUS} >= 400 && %{REQUEST_STATUS} < 600"

However, this header is not getting set on the pages, and it still redirects to the 404 page.

Is there a better and optimal approach to achieve this?

[SantoshSai]

Hi @sai_charanAr,

AEM as a Cloud Service (AEMaaCS), where custom error handling works differently from traditional AMS setups due to the immutable nature of /apps and how error handling is sandboxed and virtualized differently.

In AEMaaCS:

1. Placing 404.jsp directly under /apps/acs-commons/... can cause interference with how ACS Commons features are resolved.

2. Dispatcher-based ErrorDocument rules do work, but they cause URL changes — which breaks your desired UX.

3. The x-aem-error-pass header only works with AEMaaCS’s built-in error handling logic and needs Cloud Manager/CDN awareness to behave as expected.

I would follow these approach (for AEMaaCS)

1. Use the AEMaaCS-supported ACS Commons error handler

ACS Commons does support AEMaaCS via /apps/acs-commons/components/utilities/errorpagehandler.

But don’t override or block access to /apps/acs-commons — instead:

Place your custom error pages under your own project path, e.g.:

/apps/your-project/components/errorpages/404.jsp

Then, in your error handler logic (default.jsp under /apps/sling/servlet/errorhandler/), call your custom page using a resource include or forward, like:

<%@ include file="/libs/foundation/global.jsp" %>
<%
    request.setAttribute("javax.servlet.error.status_code", 404);
    slingRequest.getRequestDispatcher("/apps/your-project/components/errorpages/404.jsp").forward(request, response);
%>

This keeps the URL intact.

2. Dispatcher Configuration:

Use a Dispatcher ErrorDocument directive but pair it with CDN headers to ensure AEM doesn't redirect to a new URL.

Example:

In your dispatcher.any or vhost.conf:

ErrorDocument 404 /content/your-site/en/error/404.html

Header set x-aem-error-pass "true" "expr=%{REQUEST_STATUS} == 404"

This tells the CDN and Dispatcher to forward the original request internally, not redirect.

Make sure:

• The 404 page is publishable and cached

• The path is available anonymously

• The CDN is configured to respect the x-aem-error-pass behavior (via Cloud Manager CDN config or Adobe support)

3. Avoid Overriding /apps/acs-commons

Do not place your project-specific 404 page inside /apps/acs-commons — even though it's tempting. It’s a shared utility area, and in AEMaaCS, it may cause package resolution issues or conflict with ACS Commons upgrades.

Recommended Structure:

/apps/your-project/components/errorpages/404.jsp
/apps/sling/servlet/errorhandler/default.jsp

default.jsp logic:

<%
    request.setAttribute("javax.servlet.error.status_code", 404);
    slingRequest.getRequestDispatcher("/apps/your-project/components/errorpages/404.jsp").forward(request, response);
%>

Hope that helps!

Regards,
Santosh

[sai_charanAr]

Thanks @SantoshSai,

We have tried this approach before, but some pages are not recognized by the error handler because they do not end with .html. As shown in the screenshot:

Not Found The requested URL was not found on this server.

[arunpatidar · Accepted solution]

Hi @sai_charanAr 

Please check 

https://experienceleaguecommunities.adobe.com/t5/adobe-experience-manager/aem-dispatcher-errordocume... 

https://experienceleague.adobe.com/en/docs/experience-manager-learn/cloud-service/content-delivery/c...