Introduction

ArangoDB replication failures often feel confusing because different root causes can look similar at the surface. A network issue, a privilege problem, or an insufficient write-ahead-log window may all show up as a generic replication configuration failure. The fastest way to recover is to troubleshoot in a fixed order: topology, connectivity, credentials, and replication state.

Confirm the Replication Design First

Before changing anything, write down what you expect the topology to be:

• Which node is the leader.
• Which node is the follower.
• Which database or databases are involved.
• Which versions of ArangoDB are running.
• Whether the setup is asynchronous replication or part of a larger cluster story.

This sounds basic, but a surprising number of incidents come from teams mixing terminology or debugging the wrong node pair. If versions differ substantially, check compatibility before making deeper configuration changes.

curl -s http://leader-db:8529/_api/version
curl -s http://follower-db:8529/_api/version

If the versions or endpoints are not what you thought they were, fix that confusion first.

Test the Real Endpoint, Not the Convenient One

Replication frequently breaks because the follower cannot reach the exact endpoint configured for the leader, even though a human operator can reach some other hostname by hand. This happens often in containerized or service-mesh environments where internal DNS names differ from external ones.

curl -s http://leader-db.internal:8529/_api/version

Run that test from the follower side and use the same hostname and port that replication actually uses. If connectivity is flaky or mismatched, fixing database settings will not help.

Stable naming matters here. If endpoint names keep changing during debugging, the team can accidentally repair the symptom while hiding the actual cause.

Verify Credentials and Database Access

A login that succeeds is not always a replication account that has enough privileges. A dedicated replication user is easier to reason about than reusing a broad administrative account.

1// run in arangosh on the leader
2const users = require("@arangodb/users");
3users.save("replicator", "strong-pass");
4users.grantDatabase("replicator", "_system", "ro");
5users.grantDatabase("replicator", "app_db", "ro");

If the user can authenticate but not read the relevant database state, the replication setup may fail in the middle of the process and produce errors that look unrelated to permissions.

Check the Replication State API

Logs are useful, but the replication API gives you structured facts you can compare over time. Query the follower and inspect whether the applier is running, what the last error was, and whether ticks are progressing.

curl -u replicator:strong-pass \
  http://follower-db:8529/_api/replication/applier-state

Useful fields to watch include:

• 'running'
• 'lastError'
• 'lastAppliedContinuousTick'
• progress details during initial sync

If the tick never moves, you likely still have a connectivity or retention problem. If the last error points to permissions or missing logs, follow that evidence instead of restarting everything blindly.

WAL Retention Can Break Correct Configurations

One of the least intuitive replication failures happens when the follower needs historical write-ahead-log entries that the leader already discarded. In busy systems, this can happen even when connectivity and credentials are both correct. The replication link is logically valid, but the follower is asking for history that no longer exists.

That means replication reliability depends partly on operational sizing:

• How long initial sync takes.
• How fast the leader writes.
• How long old ticks remain available.

If the follower repeatedly falls behind and then cannot catch up, the configuration may be correct and the retention window may still be insufficient.

Use a Deterministic Recovery Sequence

When the setup is broken, resist the urge to restart services repeatedly. A fixed workflow is usually faster:

1. Capture current applier state and logs.
2. Confirm the leader endpoint from the follower.
3. Confirm user credentials and grants.
4. Check whether WAL retention is long enough.
5. Reinitialize the follower only after the earlier checks are clean.

Reinitialization is sometimes necessary, but it should be a controlled action, not the default response. Otherwise, you end up resetting the follower repeatedly without learning why it keeps failing.

Common Pitfalls

The biggest mistake is troubleshooting without first confirming the exact topology and endpoint names in use. Another is testing connectivity against a convenient hostname instead of the advertised replication endpoint. Teams also forget that authentication success is not the same as permission correctness, and they often overlook WAL retention until the follower has already fallen too far behind. Re-running initialization commands without capturing the previous applier state is another way to lose the evidence you actually needed.

Summary

• Replication setup failures usually come from topology, connectivity, privilege, or WAL-retention problems.
• Confirm the real leader and follower endpoints before changing settings.
• Use a dedicated replication account with explicit database access.
• Inspect applier state and tick movement for fact-based diagnosis.
• Reinitialize the follower only after the simpler failure modes have been ruled out.