# Replication errors

## Errors

1. [Failed to connect to replica {} at the endpoint {}. For more details, visit:
   memgr.ph/replication.](#error-1)
2. [Couldn't replicate data to {}. For more details, visit:
   memgr.ph/replication.](#error-1)
3. [Write query forbidden on the replica!](#error-2)
4. [Query forbidden on the replica!](#error-2)
5. [Replication clause not allowed in multicommand transactions.](#error-3)
6. [Failed to replicate to STRICT_SYNC replica 'replica_name': reason.](#error-4)

## Warning

1. [Snapshots are disabled for replicas. For more details, visit: memgr.ph/replication.](#warning-1)
2. [Multi-tenant replication is currently not supported!](#warning-2)
3. [Failed to replicate to SYNC replica 'replica_name': reason.](#error-4)

## Troubleshooting replication errors [#error-1]

1. Make sure that the Memgraph instances serving as replicas are up and running.
2. Check the firewall on your machine because it could be blocking the traffic
   requested by Memgraph.
3. Verify that there are no network problems.

## Query disabled on replica [#error-2]

Not all queries are supported on the replica.
Any query that changes data or system setup is prohibited on the replica.
MAIN is the only source of truth.

## Query not allowed on multicommand transaction [#error-3]

System queries cannot be executed inside a multicommand/explicit transaction.

## Replication failure [#error-4]

When a transaction fails to replicate to one or more SYNC or STRICT_SYNC
replicas, Memgraph reports exactly which replicas failed and why. Whether that
report is a warning or an error depends on what happened to the transaction:

| Situation | How it is reported |
|-----------|--------------------|
| The transaction is committed on MAIN, but one or more **SYNC** replicas couldn't confirm it | A `WARNING` [notification](https://memgraph.com/docs/database-management/query-metadata#notifications) with the code `SyncReplicationFailure`. The query **succeeds**. |
| The transaction is rolled back on all instances because a **STRICT_SYNC** replica couldn't confirm it | A `ReplicationException`. The query **fails**. |

What decides between the two is the outcome of the transaction: if the write is
committed on MAIN, it is a notification, and if it was rolled back everywhere,
it is an exception.

> **Warning**
>
> **Breaking change in Memgraph 3.13**: a SYNC replication failure used to be
> reported as a `ReplicationException` as well, even though the write had already
> been committed on MAIN. It is now reported as a notification. If your
> application caught the replication exception around writes, read the
> `SyncReplicationFailure` notification from the query summary instead.

The message text is the same in both cases and follows this format:

```
Failed to replicate to SYNC replica 'instance_1': <reason>.
Replica will be recovered automatically.
Transaction is still committed on the main instance and other alive replicas.
Check the status of the replicas using 'SHOW REPLICAS' query.
```

When multiple replicas fail, each failure is listed with its replica name, 
replication mode, and specific reason:

```
Failed to replicate to SYNC replicas 'instance_1' and 'instance_2': <reason>.
Replicas will be recovered automatically.
Transaction is still committed on the main instance and other alive replicas.
Check the status of the replicas using 'SHOW REPLICAS' query.
```

The possible failure reasons are:

| Reason | Description |
|--------|-------------|
| `replica is not reachable or not in sync with the main` | The replica is down, behind, or the connection could not be established. |
| `failed to obtain RPC lock (another transaction is in progress)` | Another replication transaction is already in progress on that replica. |
| `RPC communication error` | A generic error occurred during the RPC call. |
| `replica has diverged from main` | The replica's data has diverged and manual recovery may be needed. |
| `RPC timeout while replicating` | The MAIN timed out waiting for a response from the replica. |

The message also indicates the transaction outcome:
- **"Transaction is still committed on the main instance and other alive replicas."** — 
  This appears for SYNC replicas. The transaction succeeded on MAIN despite the
  replica failure, and it is delivered as a `SyncReplicationFailure` warning
  notification.
- **"Transaction was aborted on all instances."** — This appears for STRICT_SYNC
  replicas. The two-phase commit protocol ensures that if any STRICT_SYNC replica
  fails, the transaction is rolled back everywhere, and the query fails with a
  `ReplicationException`.

> **Info**
>
> Failed replicas will be recovered automatically. Check the status of replicas
> using the `SHOW REPLICAS` query.

If the failure reason is an RPC timeout, the message may include guidance
about adjusting the `deltas_batch_progress_size` coordinator setting. As of 3.13
[that setting no longer has any
effect](https://memgraph.com/docs/clustering/high-availability/ha-commands-reference#deltas_batch_progress_size)
— replicas report progress on a fixed time interval instead of after a fixed
number of deltas, and long single operations such as index population,
constraint validation and snapshot loading are covered by that reporting. An RPC
timeout on 3.13 or later points to an overloaded replica, network latency, or a
replica that genuinely stopped making progress, not to a tuning problem.

## Snapshots are disabled for replicas [#warning-1]

Because of consistency constraints, snapshots are disabled on replicas. If you
need a snapshot of the database, then create one on the main instance.