• Global. Remote. Office-free.
  • Mon – Fri: 8:00 AM to 5:00 PM (Hong Kong Time)
English
Los Angeles Branch

When Multi-Region AEM Sites Break: Fixing MSM Design and Verifying CDN Routing

By Vuong Nguyen March 16, 2026 10 min read

One day, our authoring team reported an issue while creating regional page variants using Live Copy in Adobe Experience Manager (AEM).

Our platform runs multiple regional sites and languages — including the United States, Europe, and Japan — from a centralized Language Master site root, where the blueprint content resides.

The situation can be represented by the following debugging flow.

From the diagram above, two possible issues appear:

  • MSM inheritance misconfiguration
  • Incorrect request routing at the root domain

First, the MSM content structure is checked to determine why the EU page references the US footer Experience Fragment.

Understanding Multi-Region Architecture in AEM

Multi-region site architecture in AEM is built on Multi-Site Manager (MSM).

Below, blueprint pages (source) push content to regional sites via rollout and synchronization.

From this, we see that the eu/en page may reference the US XF footer instead of a regional one defined in the blueprint.

There are two ways to fix this:

  • Fix the footer reference in the template (Content / MSM)
  • Use MSM Live Copy to manage region-specific XF references

Start with the template. Without changing backend logic, authors often duplicate templates and hardcode a footer per region.

Below shows how this workaround works and why it creates more problems over time.

Start with the template. Without changing backend logic, authors work around the limitation by duplicating templates and assigning a fixed footer per region.

Each template hardcodes an XF reference, so authors switch templates instead of fixing the underlying structure.

The diagram below shows how this workaround expands over time and creates structural issues.

Root issue lies in template structure controlling content. Move XF from locked structure into editable content.

Updated structure after the change:

jcr:content
└─ root
   └─ container
      ├─ container_1231161868
      │  └─ header XF (locked)
      │
      ├─ container (editable=true)
      │  └─ hero / content 
      │
      └─ container_footer (editable=true)
         └─ experiencefragment_f
            fragmentVariationPath = /content/.../language-masters/en_eu/...

XF now lives in page content, not in the template structure. MSM rollout preserves regional references, and authors update the footer directly on the blueprint page.

Instead of modifying the template, MSM Live Copy can manage XF references at the content level.

Managing XF References with MSM Live Copy

MSM Live Copy controls how Experience Fragment (XF) references vary across regions. This works only when blueprint content and regional structure are clearly separated.

Blueprint defines the content:

/content/<site>/language-masters
└── en   (single language source)
    ├── home
    ├── privacy-policy

Live Copy defines the regional structure:

/content/<site>
├── eu/en
├── jp/en
├── us/en

A single blueprint page holds one XF reference, but regional needs (e.g., different footers) force variation—handling this at the content level leads to duplication and inconsistency.

To avoid this, keep one language-based blueprint as the source of truth:

  • /language-masters/en defines shared content
  • All regional sites inherit from this structure

Resolve regional differences during rollout—not in the blueprint—using a custom LiveCopyAction.

Below is the full flow—from blueprint creation to regional XF reference update.

Even with this design correctly implemented, the site still produced unexpected results in certain regions.

When accessing the root domain, requests were consistently routed to an incorrect regional path (for example, /us/en), leading to the wrong content being rendered.

At first, this appeared to be an MSM inheritance issue.

However, the problem started earlier in the request flow—at the CDN routing layer—before AEM content logic was applied.

When MSM Works but the Wrong Content Is Served

Even with correct MSM setup, request routing to AEMaaCS caused some pages to render wrong content.

See diagram below for request flow to AEMaaCS.

CDN configuration defines routing behavior.

Example rule:

- name: com-root-redirect
  when:
    allOf:
      - reqProperty: tier
        in: ["publish","preview"]
      - reqProperty: domain
        matches: ".*(shiftsaas|adobeaemcloud).(com|net)"
      - reqProperty: path
        like: "/"
  action:
    type: redirect
    location: /us/en

In Europe, accessing root path (“/”) does not route to /eu/en.

  • CDN redirects request to /us/en.
  • AEM renders /us/en content, including US XF.
  • EU page is never requested, so EU XF is not applied.

CDN fixes the path before AEM runs, so AEM does not select region.

Correct flow removes this constraint.

Integrating Sling Resource Resolver with MSM enables automated region selection and JCR content mapping.

AEM resolves content by processing a URL into a Resource, which then determines the execution Script.

Resolution flow:

Example:

  • Request: https://eu.example.com/
  • Sling maps domain to /content/site/eu/en
  • Resource resolved: /content/site/eu/en/jcr:content
  • Script resolved: page component (HTL)

Two primary mechanisms—JCR-based /etc/map and resource.resolver.mapping—define how Sling resolves request paths.

  • /etc/map (JCR-based mapping, supports domain routing, regex, internalRedirect)
  • resource.resolver.mapping (simple rules, not used for domain routing in this case)

Request lifecycles flow from initial URL resolution through /etc/map to the final Experience Fragment (XF).

/etc/map.prod configurations define the translation between external domains and internal content paths.

/etc/map.prod/https/www.shiftsaas.com/.content.xml

Incoming domains map directly to a content root path where JCR structures define the specific region (e.g., /eu/en).

<?xml version="1.0" encoding="UTF-8"?>
<jcr:root xmlns:sling="http://sling.apache.org/jcr/sling/1.0" xmlns:jcr="http://www.jcp.org/jcr/1.0"
          jcr:primaryType="sling:Mapping"
          sling:internalRedirect="[/content/shiftsaas]">
    <redirect/>
    <reverse/>
</jcr:root>

Sling maps domain to content path using this rule:

www.shiftsaas.com → /content/shiftsaas

Domain resolves to a content root path, where content structure defines region (/eu/en, /us/en), and MSM applies inheritance after page resolution.

Redirect mapping:

src/main/content/jcr_root/etc/map.prod/https/www.shiftsaas.com/redirect/.content.xml

Redirect mapping aligns incoming URL patterns with internal repository hierarchies by rewriting the request path.

<?xml version="1.0" encoding="UTF-8"?>
<jcr:root xmlns:sling="http://sling.apache.org/jcr/sling/1.0" xmlns:jcr="http://www.jcp.org/jcr/1.0"
          jcr:primaryType="sling:Mapping"
          sling:internalRedirect="[/content/shiftsaas/$1,/$1]"
          sling:match="(.+)$"/>

Reverse mapping:

src/main/content/jcr_root/etc/map.prod/https/www.shiftsaas.com/reverse/.content.xml

Reverse mapping maintains URL integrity by transforming internal JCR paths back into user-friendly external URLs.

<?xml version="1.0" encoding="UTF-8"?>
<jcr:root xmlns:sling="http://sling.apache.org/jcr/sling/1.0" xmlns:jcr="http://www.jcp.org/jcr/1.0"
          jcr:primaryType="sling:Mapping"
          sling:internalRedirect="[/content/shiftsaas/(.*).html]"
          sling:match="$1"/>

Mapping rules define how URL patterns translate into JCR content paths.

Resolving Regional Roots via Sling Mapping

Sling Resource Mapping translates regional entry URLs into internal JCR paths, so each request maps directly to a defined regional content root.

Current structure example:

── etc
    ├── acs-commons
    │   └── lists
    │       └── icon-library
    ├── map.dev
    │   └── https
    │       ├── publish-dev.shiftsaas.com
    │       │   ├── redirect
    │       │   └── reverse
    │       └── publish-qa.shiftsaas.com
    │           ├── redirect
    │           └── reverse
    ├── map.stage
    │   └── https
    │       └── publish-stage.shiftsaas.com
    │           ├── redirect
    │           └── reverse
    └── map.prod
        └── https
            └── www.shiftsaas.com
                ├── redirect
                └── reverse

The current structure fits portal-style use cases, but it lacks clear separation for multi-region experience sites. Therefore, regional routing should be more explicitly defined.

Next section outlines alternative structures and refactoring options.

Option 1: Path-Based Mapping (Single Domain)

Path-based mapping routes URL prefixes (e.g., /eu/en) to regional content paths under one domain, so the domain remains consistent while regional logic is handled through URL paths.

Example:

/etc/map.prod
└── https
    └── www.shiftsaas.com
        ├── us-en (Node: sling:Mapping)
        │   ├── sling:internalRedirect: [/content/shiftsaas/us/en/$1]
        │   └── sling:match: us/en/(.+)$
        ├── eu-en (Node: sling:Mapping)
        │   ├── sling:internalRedirect: [/content/shiftsaas/eu/en/$1]
        │   └── sling:match: eu/en/(.+)$
        └── gb-en (Node: sling:Mapping)
            ├── sling:internalRedirect: [/content/shiftsaas/uk/en/$1]
            └── sling:match: uk/en/(.+)$

Option 2: Host-Based Mapping (Multi-Domain Migration)

Host-based mapping assigns each region to a dedicated domain, so each request resolves directly to its regional content root.

As a result, regional context is determined at the domain level, and path parsing is no longer required.

Example:

/etc/map.prod
└── https
    ├── www.shiftsaas.com        (US Default)
    │   ├── redirect               (return /content/shiftsaas/us/en)
    │   └── reverse
    ├── eu.shiftsaas.com         (Europe)
    │   ├── redirect               (return /content/shiftsaas/eu/en)
    │   └── reverse
    └── uk.shiftsaas.com         (United Kingdom)
        ├── redirect               (return /content/shiftsaas/uk/en)
        └── reverse

Mapping strategy defines the point of region resolution in the request lifecycle.

  • Path-based mapping: Region comes from the URL, so AEM resolves it via /etc/map → inside AEM (late)
  • Host-based mapping: Region comes from the domain, so CDN resolves it before AEM → at edge (early)

Path-based mapping:

  • www.site.com/eu/en/page
  • CDN passes request
  • Dispatcher → AEM
  • /etc/map resolves to /content/site/eu/en
  • AEM serves content
    → Region is resolved inside AEM (late)

Host-based mapping:

  • eu.site.com/page
  • CDN maps domain → /content/site/eu/en
  • Dispatcher → AEM
  • AEM serves content directly
    → Region is resolved at CDN (early)

cdn.yml handles region routing at the edge for host-based mapping, while /etc/map resolves content paths inside AEM and focuses on site structure.

This separation reduces complexity and keeps request handling predictable.

Wrapping up

Multi-region success in AEM depends on alignment between edge routing and internal resource resolution. When these layers diverge, regional leakage occurs and incorrect content is served despite valid MSM structures.

Strategy Selection

  • Path-based mapping fits single-domain strategies, while shifting complexity to Sling mapping rules.
  • Host-based mapping enables scalable architecture, while resolving region at the edge for cleaner request flows.

Strategic Takeaways

  • Isolate responsibilities: CDN handles entry routing, while AEM resolves JCR paths.
  • Protect content roots: Each region maps to a distinct JCR root to avoid XF conflicts.
  • Enforce reverse mapping: Internal repository paths stay hidden from external URLs.

Clear separation between routing and resolution establishes a predictable flow from request to resource to regional experience.

What’s next

Regional routing and MSM inheritance now align, while two SEO-critical layers remain: canonical resolution and hreflang integration.

Canonical Link Behavior During Regional Redirects

Requests to /region>/<language>/* can resolve to /region>, so the parent path gets indexed instead of the full regional URL. This happens when redirect chains collapse before AEM completes resource mapping.

The next article focuses on:

  • Why canonical tags resolve to /region> instead of /region>/<language>/page
  • How Sling resolution interacts with redirect chains
  • How to fix canonical output at component or rewriter level

Hreflang Integration for Multi-Region Sites

Canonical stability enables reliable hreflang signals, while incorrect canonicals cause hreflang to point to the wrong regional variant and create duplicate signals.

The next article focuses on:

  • Generating hreflang tags from MSM Live Copy relationships
  • Mapping /region>/<language> paths to correct hreflang locales
  • Validating hreflang via Google Search Console and avoiding misconfigurations