Troubleshooting Replication Agents

Replication is how content travels from Author to Publish. When it works, nobody thinks about it. When it fails, authors click Publish, nothing appears on the live site, and the first message arrives within minutes. This post explains how replication works on AEM 6.5 and on AEM as a Cloud Service, and gives you a practical way to troubleshoot each.

Two Very Different Models

The authoring experience is the same in both: authors click Publish and AEM does the rest. What changes is what's underneath, and therefore how you diagnose problems.

Part A: Replication Agents (AEM 6.5 / AMS)

How an Agent Works

When an author activates a page:

1. AEM creates a replication request and places it in the queue of each enabled agent
2. The agent builds a package of the content and sends it over HTTP (the transport URI) to the Publish instance
3. Publish receives and stores the content
4. A Dispatcher Flush agent (on Publish, or Author depending on topology) then asks Dispatcher to invalidate its cache

The Agents You'll Meet

You'll find them at Tools → Deployment → Replication, with agents on Author listed under Agents on author.

Reading an Agent's Status

Open an agent and check:

• Enabled / Disabled: a disabled agent silently does nothing
• Queue state: Idle is healthy. Processing is fine if short-lived. Blocked means the first item can't be delivered, and everything behind it is waiting
• Queue length: a growing queue means items are being added faster than delivered, or delivery is stuck
• Test Connection: verifies that Author can reach the transport URI with the configured credentials
• View Log: the agent's own log, which usually names the problem

Common Failures and Fixes

1. Queue is "Blocked"

A blocked queue means the item at the head can't be delivered, and the agent keeps retrying. The cause is nearly always in the log:

• Connection refused / timeout: Publish is down, a firewall rule changed, or the transport URI or port is wrong. Fix the connectivity, and the queue drains by itself
• 401 or 403: the transport user's credentials are wrong or expired, or it lacks permissions on Publish. Re-enter the credentials in the agent's Transport settings and check the user's rights
• A specific bad item: if one item fails forever, use Clear on that item (or Force Retry after you've fixed the cause) so the rest of the queue can proceed

2. "Test Connection" fails

• Check the transport URI, typically http://publish-host:4503/bin/receive?sling:authRequestLogin=1
• Check the transport user and password
• Check network access from the Author host to Publish (for example with curl from the Author server)
• Check that the Publish instance is running and its Sling POST servlet and replication receiver are available

3. Content published but isn't visible on the live site

Replication may have succeeded, so look at the layers after it:

• Request the page directly from Publish. If the new content is there, replication worked, and the problem is Dispatcher or CDN caching (see Part 1)
• Check the Dispatcher Flush agent: is it enabled, is its queue clear, and does Dispatcher accept flush requests from that host?

4. Authors get permission errors when publishing

The author's user needs Replicate permission on the content. Check the ACLs and the user's group memberships. Page-level restrictions can also block publishing, such as pages locked for editing or pending workflow.

5. A page publishes, but its images or other references are missing

Referenced assets and pages have to be published too. In the Publish dialog, review the list of references, and make sure the author includes them. Missing dependencies are one of the most common causes of broken pages on Publish.

6. Large publishes are slow or time out

• Publish in smaller batches (use Manage Publication and schedule later if necessary)
• Check Author and Publish resource usage, because replication competes with other work
• Review the agent's timeout and retry settings

Logging for Deeper Investigation

When the agent log isn't enough, add a dedicated logger:

1. Open the Felix console at /system/console/slinglog
2. Add a new logger for com.day.cq.replication at DEBUG level, writing to its own file such as logs/replication.log
3. Reproduce the problem, then inspect that file

Remember to turn it back down when you're done, since debug logging on replication is noisy.

You should also look at Sling Jobs (/system/console/slingevent), because replication runs as jobs, and a stuck or failing job queue shows up there.

Triggering Replication from Code

Custom code uses the Replicator service:

@Reference
private Replicator replicator;

public void publish(ResourceResolver resolver, String path) throws ReplicationException {
    Session session = resolver.adaptTo(Session.class);
    replicator.replicate(session, ReplicationActionType.ACTIVATE, path);
}

Use the right action type (ACTIVATE, DEACTIVATE, DELETE), run as a user or service user that has Replicate permission, and catch ReplicationException so a failure is logged rather than lost.

Part B: Replication on AEM as a Cloud Service

What's Different

On Cloud Service, content is published using Sling Content Distribution, which moves the content to a pipeline service that runs on Adobe I/O, outside the AEM runtime. The replication agents used in previous versions are no longer used or provided. There is nothing to create, no transport URI to manage and no agent queue to unblock by hand.

The Replicator API still exists for custom code, so the Java above continues to work. What changed is the machinery underneath it.

What That Means for Troubleshooting

You can't open an agent, so your tools are:

• Author UI: check whether the page actually shows as published and when
• Logs: download Author and Publish logs through Cloud Manager or view them in the Developer Console, and look for distribution-related errors around the time of the activation
• Sling jobs and queues (where exposed in your environment), for stuck distribution work
• Direct requests to Publish or the CDN to find where the content stops being fresh
• Support: if distribution looks broken platform-wide, open a ticket with Adobe, because the pipeline is Adobe-managed

Problems You Can Fix Yourself

• Content published but not visible: check the CDN and Dispatcher layers (Part 1). A stale CDN edge is far more common than a failed distribution
• Referenced content missing: same as on 6.5: publish the references, including assets and fragments
• Permission errors: the same ACL and group checks apply
• Custom code that relied on replication agents: any code that creates, reads or configures agents needs to be refactored for Cloud Service, since the agents don't exist. Adobe's pattern-detection tooling flags this during migration planning
• Workflows that used reverse replication: this isn't initially supported on Cloud Service, so design a different way to move user-generated content, for example by writing it to an external service from Publish

Testing Locally

Be careful about conclusions drawn from the local SDK. The local SDK doesn't include Adobe's managed distribution pipeline, journal or cloud microservices, and local replication uses classic author-to-publish mechanisms. That means you can test that your code triggers a publish, but you can't fully validate distribution behavior, queue handling or failure modes without a real cloud environment. Test those on Dev or Stage.

A Troubleshooting Flow That Works on Both Models

When "I published it and it isn't live":

1. Was it really published? Check the page status and last-published date on Author
2. Did replication succeed? On 6.5, check the agent queue and log. On Cloud Service, check logs for distribution errors
3. Is the new content on Publish? Request the page directly from Publish
4. Did Dispatcher refresh? Check the .stat file and cached file timestamps, and the flush logs
5. Is the CDN holding an old copy? (Cloud Service) Check Age and Cache-Control headers
6. Are references and permissions in order? Publish dependencies, check the Replicate permission

Working from left to right through the pipeline (Author → replication → Publish → Dispatcher → CDN → browser) finds the layer that's out of date quickly, and stops you from "fixing" the wrong thing.

Preventing Replication Problems

• Monitor queue depth and blocked queues (6.5) with alerts, so you hear about problems before authors do
• Use service users with minimal permissions for transport and custom replication code
• Rotate and document credentials for transport users
• Keep Publish instances healthy, because replication failures are often symptoms of an overloaded or unreachable Publish
• Train authors to check the references list when publishing, and to use scheduled publishing for large batches

What's Next

We've now seen how the platform differs for replication and Dispatcher. In the next post we compare AEM as a Cloud Service and AEM 6.5 side by side, so you know what changes for developers, operations and architecture.

Next in this series: [AEM as a Cloud Service vs 6.5 On-Prem]