Documentation

On-premise sling mappings fail after migrating to AEMaaCS

Last update: Mon Aug 25 2025 00:00:00 GMT+0000 (Coordinated Universal Time)

Migrating sling mappings from an on-premise AEM setup to Adobe Experience Manager as a Cloud Service (AEMaaCS) introduces compatibility issues due to the immutable nature of the cloud environment. To resolve the issue, restructure and deploy sling mappings using the supported cloud-compatible format.

Description description

Environment

Adobe Experience Manager as a Cloud Service (AEMaaCS) – Sites

Issue/Symptoms

  • Mappings for multiple paths and domains fail to generate correct URLs.
  • Forward and reverse mappings under /etc/map don’t work in AEMaaCS.
  • The outgoing URLs appear incorrect, but redirect to the right destination.
  • The incoming URLs behave correctly, but the outgoing behavior is inconsistent.
  • AEMaaCS requires Sling mappings to be deployed via code due to AEMaaCS’s immutability.

Resolution resolution

Follow these steps to convert and deploy sling mappings compatible with AEMaaCS:

  1. Export existing sling mappings from the on-premises /etc/map directory into a .zip package.

  2. Add the exported .zip package to your project codebase underyour_project/ui.content/src/main/content/jcr_root/.

  3. Rename the map folder inside the etc directory to map.publish.

  4. Update the Apache Sling Resource Resolver configuration to reference /etc/map.publishas the mapping location.

    1. Create or update the OSGi configuration JSON for the PID org.apache.sling.jcr.resource.internal.JcrResourceResolverFactoryImpl.
    2. Set resource.resolver.map.location to /etc/map.publish.
    3. Optionally, update resource.resolver.mapping with any custom array values if you’re migrating mapping logic out of JCR.

  5. Save all changes and deploy the updated codebase using Adobe Cloud Manager to push changes to AEMaaCS.

  6. Test the mappings thoroughly in Development and Staging environments to ensure both incoming and outgoing URLs behave correctly before deploying to Production.

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