Common AEM Replication and Publishing Issues: A Troubleshooting Guide

When AEM content does not appear on the live site, first identify which boundary failed: authoring, publication, publish rendering, Dispatcher, or CDN. “Replication is broken” is often an inaccurate diagnosis for a cache problem, missing dependency, or permission failure.

Map the publication path

In a typical AEM 6.5 topology, activation sends content from author through a replication agent to publish. In AEM as a Cloud Service, managed distribution handles that movement. After content reaches publish, Dispatcher and possibly a CDN must stop serving the stale representation.

Test each boundary with one known page and timestamp. Record the author content state, publication event, publish response, Dispatcher response, and public response. This creates evidence without repeatedly republishing and obscuring the original failure.

Issue 1: the queue is blocked

In AEM 6.5, inspect the replication agent and its queue. Start with the oldest entry: one failing item can prevent later items from progressing. Review logs for connection refusal, timeout, TLS, authentication, serialization, and repository errors.

Confirm network reachability and credentials through approved operational tools. Do not delete the queue as a first response. That removes evidence and can discard unpublished changes. Pause the agent if necessary, resolve or isolate the failing item, test the connection, and then resume while monitoring throughput.

For Cloud Service, inspect the publication workflow and distribution status available for the environment. Use cloud logs to distinguish a rejected content operation from a delivery delay. The Cloud Service architecture guide explains the different topology.

Issue 2: the user cannot publish

A user may edit a page but lack permission to replicate it, publish a referenced asset, or read part of the subtree needed by a workflow. Test with a representative non-administrator account and review effective permissions for the content, referenced DAM folders, and workflow paths.

Avoid solving the problem with broad administrator rights. Assign publication through groups and workflows that match governance. In a multi-region program, regional editors may publish local content while central teams retain control of shared navigation, legal copy, and global assets.

Issue 3: dependencies are missing

A page can reach publish while its image, Content Fragment, Experience Fragment, tag, redirect target, or client library does not. The result may be an incomplete page rather than a publication error.

Review references before publication and define whether the workflow includes them. Be careful with automated tree activation: it can publish unintended drafts or create a large queue. For headless content, publish the model, persisted query, fragment, references, and assets required by the response. The Content Fragments and GraphQL tutorial covers that chain.

Issue 4: publish is correct but the site is stale

Fetch the page from publish through an approved diagnostic route, then through Dispatcher, then through the public host. If publish is current but Dispatcher is not, inspect flush events, cache files, .stat timestamps, and invalidation scope. If Dispatcher is current but the public host is stale, investigate CDN cache keys and purge behavior.

Shared content creates non-obvious dependencies. Updating a navigation fragment can affect hundreds of pages whose own paths were never activated. Use explicit dependency invalidation, suitable cache lifetimes, or a rendering design that avoids permanently stale composites. Follow the Dispatcher troubleshooting guide for a layer-by-layer sequence.

Issue 5: one item repeatedly fails

If only one page fails, compare it with a working sibling. Check path length and characters, locks, permissions, damaged references, oversized payloads, custom event handlers, and workflow code. Look for the first server-side exception tied to the event.

Do not repair repository data directly in production unless an approved Adobe procedure requires it. Reproduce the content shape in a lower environment and fix the authoring model, migration, or custom code that created the invalid state.

Issue 6: publishing is slow at scale

Large launches can overwhelm queues, publish processing, cache invalidation, and downstream integrations. Batch content deliberately, publish dependencies first, and monitor queue depth and error rate. Avoid scheduling every region to launch through one narrow operational window unless that is a true business requirement.

For releases spanning the US, UK, India, and Australia, define who can pause publication, how teams communicate failed paths, and when the public result is considered verified. Technology cannot replace a single launch record and clear ownership.

Build a useful incident record

Capture the content path, environment, action time, user, publication identifier, first error, current queue state, and responses from each delivery layer. Redact credentials and personal data. This record helps support teams investigate and prevents the same incident from being rediscovered on the next shift.

Learn AEM operations and delivery in the AEM Developer and Architect course. For help isolating a publishing incident, contact us.