Why an item fails to get replicated?

There are many reasons why replication of an item fails and the replication queue gets built up. Some of the common reasons to check for are

1. Agent configuration
2. Network issue
3. Permissions issue
4. Missing namespaces / node types
5. Oak conflicts

Agent configuration
The reason for replication not working could simply be because the agent configuration is wrong.

If you are doing the configuration for the first time or making any changes to the configuration, make sure to perform ‘Test connection’ check to make sure that there is no inadvertent error in the configuration.

Network issue
Replication failures are often caused by network issues. It could be a temporary glitch in which case the queue items gets cleared once the network is restored.

A java.net.ConnectException in the logs of the sender AEM instance is an indication of network issue preventing replication from being successful.

You could see messages like

Error while sending request: java.net.ConnectException: Connection refused: connect

On the sender side error.log file.

Permissions issue
Replication could fail if the transport user does not have write permission for the replicated content on the target instance.

The issue occurs when the replication process installs the replicated content on the receiver end. You would see error message indicating ‘Access denied’ in the logs.

Error message would read as

com.day.cq.replication.ReplicationException: Repository error during node import: Access denied.

On the sender and receiver side error.log file.

Missing namespaces / node types
The custom namespaces and node types that are created must be created on the publish side as well.

Typically, the namespaces and node types creation should be included in the code package so that it gets installed on all instances.

If it gets missed out and if the item replicated used custom node types or name spaces, replication could fail.

This can be detected by looking for “Invalid namespace prefix” and “Invalid node type” messages in the error.log

Oak conflicts
Replication might fail due to conflicts when writing content to the oak repository.
This is more likely to happen on instances configured with Mongo repository when more than on instance shares a common repository.

Look for messages with “Unresolved conflicts” to identify issues due to oak conflicts

Closing Note
The above are only some of the main reasons for replication failure. It is not an exhaustive list of all the reasons for replication failures.

For any replication issue, perform these three basic checks

1. Perform test connection to make sure connectivity is not an issue
2. Check the error.log on the sender side. This would almost always give you the cause of the issue
3. Check the error.log on the receiver side for more details on the cause of the issue.