Documentation

Preserve X-Correlation-Id in AEMaaCS error responses (404/500)

Last update: Fri Nov 14 2025 00:00:00 GMT+0000 (Coordinated Universal Time)

In Adobe Experience Manager as a Cloud Service, you use the X-Correlation-Id header to trace requests across AEM, Dispatcher, and CDN layers. While this header appears in successful (200 OK) responses, it’s missing in error responses like 404 Not Found or 500 Internal Server Error, even though AEM logs confirm it was set. By default, CDN replaces AEM error responses with synthetic pages, which strips custom headers. This breaks monitoring and debugging workflows, making it difficult to correlate client-side failures with backend logs.

To fix this, add the x-aem-error-pass: true header to error responses. This tells the CDN to forward the original AEM response instead of generating a synthetic error page, ensuring the X-Correlation-Id header is preserved in all response types.

Description description

Environment

  • Adobe Experience Manager as a Cloud Service (AEMaaCS)
  • CDN configurations using responseTransformations
  • Context: When implementing correlation IDs or tracing mechanisms across AEM, Dispatcher, and CDN

Issue/Symptoms

  • X-Correlation-Id header is present in 200 OK responses but missing in 404 or 500 responses.
  • AEM logs show the header is set, but it doesn’t reach the browser or API client. Noticed when validating request tracking or debugging behavior using cURL, Postman, or browser developer tools.
  • Monitoring systems fail to trace failed transactions due to missing correlation headers.
  • CDN configurations appear to suppress headers in error responses.

Resolution resolution

To allow AEM’s original error response and its headers to reach the client:

  • Configure your AEM error handler to include the header x-aem-error-pass: true in error responses.

  • This instructs the CDN to bypass synthetic error page generation and forward the original AEM or Dispatcher response (including its headers) directly to the client.

  • After applying this change:

    • The X-Correlation-Id header appears in both successful and failed responses.
    • Client-side monitoring tools can trace the full request lifecycle accurately.

Additional considerations:

  • Security & compliance: Make sure error payloads don’t expose sensitive internal details before enabling this header in production.
  • Scope: This behavior applies only to responses generated by AEM or Dispatcher. CDN-level errors will still serve synthetic pages.
  • Common misunderstanding: responseTransformations can’t re-inject headers in synthetic error responses.
  • Testing tip: Use curl -i -v or browser developer tools to verify header presence before and after applying the fix. For example, -i -v https:///path-that-triggers-error

Best practice recommendation:

  • Always generate and set a correlation ID in backend requests.
  • Include the same ID in logs and headers.
  • Use x-aem-error-pass: true for error responses that require full traceability, especially during debugging or integration testing.
  • Limit usage in production to controlled scenarios to avoid overriding CDN’s standard error handling.
recommendation-more-help
3d58f420-19b5-47a0-a122-5c9dab55ec7f