ClickHouse DB::Exception: Unsatisfied quorum for previous write

The DB::Exception: Unsatisfied quorum for previous write error (code UNSATISFIED_QUORUM_FOR_PREVIOUS_WRITE) means that a prior INSERT with quorum requirements has not yet been acknowledged by the required number of replicas. ClickHouse blocks subsequent quorum writes to the same table until the previous one completes, preventing out-of-order consistency issues.

Impact

New INSERT operations to the affected table are rejected until the pending quorum write either succeeds or times out. This can cause a cascade of write failures in applications, leading to data ingestion delays. Read operations continue to work normally against already-committed data.

Common Causes

Slow replication -- one or more replicas are lagging behind, so the previous write has not been replicated to enough nodes yet.
Replica went down after the write -- the write landed on the leader, but a replica failed before confirming receipt, leaving the quorum incomplete.
Network issues between replicas delaying part fetches.
High insert concurrency without insert_quorum_parallel enabled, causing sequential blocking.
ZooKeeper latency preventing timely quorum status updates.

Troubleshooting and Resolution Steps

Identify the pending quorum write Check ZooKeeper for the quorum status node:

SELECT *
FROM system.zookeeper
WHERE path = '/clickhouse/tables/01/my_table/quorum/last_part';

Check replication queue and lag

SELECT database, table, replica_name, queue_size, inserts_in_queue,
       absolute_delay, last_queue_update
FROM system.replicas
WHERE table = 'my_table';

Look for replicas with large absolute_delay or high queue_size.

Verify all replicas are active
```
SELECT database, table, total_replicas, active_replicas
FROM system.replicas
WHERE table = 'my_table';
```
If active replicas are fewer than the quorum requirement, bring the missing nodes back online.
Wait for replication to catch up Force a sync and wait:
```
SYSTEM SYNC REPLICA db.my_table;
```
This blocks until the replica has processed all entries in its queue.
Enable parallel quorum writes If you are on ClickHouse 22.3 or later, enable parallel quorum to prevent sequential blocking:
```
SET insert_quorum_parallel = 1;
```
This allows new quorum inserts to proceed without waiting for previous ones.
Reset the quorum state (last resort) If the quorum entry is stuck and the pending part has actually been replicated:
```
# Remove the stale quorum node in ZooKeeper
zkCli.sh deleteall /clickhouse/tables/01/my_table/quorum/last_part
```
Exercise extreme caution with this approach.

Best Practices

Enable insert_quorum_parallel to avoid head-of-line blocking on quorum writes.
Set insert_quorum_timeout to a reasonable value (e.g., 30-60 seconds) so that stuck quorum writes eventually time out rather than blocking indefinitely.
Monitor replication lag across all replicas and alert when it exceeds a threshold.
Ensure replicas have sufficient network bandwidth and disk I/O to keep up with the write rate.
Use connection retry logic in your application to handle transient quorum failures gracefully.

Frequently Asked Questions

Q: How long will ClickHouse wait for the previous quorum to be satisfied?
A: It depends on insert_quorum_timeout, which defaults to 600 seconds (10 minutes). After this timeout, the quorum write is considered failed.

Q: Does this error mean the previous write was lost?
A: Not necessarily. The data may have been written to the leader replica; it simply has not been confirmed on enough replicas to meet the quorum. Once replication catches up, the quorum may still be satisfied.

Q: Can I safely disable quorum writes temporarily to unblock my pipeline?
A: Yes, setting insert_quorum = 0 at the session level will bypass quorum checks. Be aware that this reduces write durability guarantees until you re-enable it.

Q: What is the difference between this error and TOO_FEW_LIVE_REPLICAS?
A: TOO_FEW_LIVE_REPLICAS means not enough replicas are currently active to even attempt a quorum write. UNSATISFIED_QUORUM_FOR_PREVIOUS_WRITE means enough replicas exist, but a prior quorum write is still pending confirmation.