Adobe Experience Manager: Fixing broken navigation and asset links due to missing dispatcher path mappings
This article explains how to resolve broken navigation and asset links in Adobe Experience Manager (AEM) Sites when dispatcher path mappings are missing or incomplete after maintenance or dispatcher cache refreshes.
Description description
Environment
Adobe Experience Manager Sites (AEM Sites), all supported versions and deployment models using the dispatcher module
Symptoms
After scheduled maintenance or dispatcher cache refreshes, navigation links and image asset paths across the site become broken. Affected links output URLs starting with either /content/<site-context>/... (which work) or /<site-context>/... (which don’t work). Prior to the issue, neither of these path patterns appeared in link paths. The issue also impacts image paths, resulting in broken images throughout the site.
Cause
A missing or incomplete dispatcher path mapping for the site context causes URLs to be generated that don’t resolve correctly. This configuration gap is often exposed after dispatcher cache clears or maintenance activities, leading to unmapped URLs and broken links and assets.
Resolution resolution
Follow the steps below to resolve the issue:
-
Review your dispatcher configuration files for missing path mappings related to your site’s context path.
-
Inspect mapping files (such as
aem-base-uris.txtor equivalent) to ensure all required mappings are present for your site context. -
Add a mapping from
/<site-context>to/content/<site-context>in the dispatcher configuration. For example:/<site-context> /content/<site-context> -
If needed, configure a dispatcher 301 redirect to canonical vanity URLs to ensure consistent URL resolution.
-
After updating the configuration, clear the dispatcher cache to apply the changes.
-
Verify that navigation links and image asset paths now resolve correctly across the site.
-
If replication agents were paused during maintenance, resume their operation.