Documentation

Fixing client domain routing issues in AEM as a Cloud Service

Last update: Mon Sep 22 2025 00:00:00 GMT+0000 (Coordinated Universal Time)

Client domain routing in Adobe Experience Manager as a Cloud Service (AEMaaCS) fails when dispatcher farms are misconfigured, causing requests to default to the wrong farm. To resolve this, validate dispatcher setup, update virtual host aliases, rename farm files to fix ordering, review client headers, and verify CDN settings for correct domain mapping.

Description description

Environment

Adobe Experience Manager as a Cloud Service (AEMaaCS) – Sites, production environment using Akamai CDN with domain certificates and multiple custom domains.

Issue/Symptoms

  • Dispatcher logs display warnings such as: No farm matches host ‘localhost’, selected last farm ‘publishfarm’.
  • The dispatcher configuration appears to prioritize enabled farms in reverse alphabetical order.
  • Symlinks for files within the enabled_vhosts and enabled_farms directories are missing.
  • Certain required server aliases such as localhost, 127.0.0.1 are absent from the virtual host configuration.

Resolution resolution

To resolve this issue, follow these steps:

  1. Validate Dispatcher Configuration:

    • Use the Dispatcher validation tool locally to identify any errors or warnings in the current configuration.
    • Ensure that all files within the enabled_vhosts and enabled_farms directories are symlinks.

  2. Update Virtual Host Configuration:  Confirm that virtual host entries include all necessary server aliases: ServerAlias "*example.com" "*.local" "localhost" "127.0.0.1" "*.adobeaemcloud.net" "*.adobeaemcloud.com"

  3. Rename Enabled Farms:  Remove numeric prefixes (for example, 00_, 01_) from enabled farm filenames, as these may cause reverse alphabetical ordering issues during farm selection.

  4. Enable Debug Logging:  Set dispatcher logs to debug mode and capture log snippets related to farm selection or error occurrences for further analysis.

  5. Review Client Header Rules:  Inspect client header rules (For example, clientheaders.any and default_clientheaders.any) for hardcoded placeholder values such as 'localhost'. Replace these with appropriate mappings for incoming requests.

  6. Test Changes Locally:  Deploy the updated configuration on a local Dispatcher instance and validate functionality before applying changes to production.

  7. Deploy Updated Configuration:  Once validated, deploy the updated Dispatcher configuration using your pipeline tools.

  8. Verify CDN Settings:

    • Ensure that the CDN is correctly configured to use customer domain names.
    • Validate that the X-Forwarded-Host header is set appropriately and does not contain placeholder values like 'localhost'.

  9. Re-Test Domain Routing:  After deployment, test each custom domain to confirm that requests are routed correctly to their respective farms.

  10. Monitor Logs Post Deployment:  Continue monitoring Dispatcher logs after deployment to identify any anomalies or recurring issues.

recommendation-more-help
3d58f420-19b5-47a0-a122-5c9dab55ec7f