apache/cassandra · error · CoordinatorBehindException

Write request failed due to coordinator behind

Error message

Write request failed due to coordinator behind

What it means

A WriteTimeoutException variant raised by AbstractWriteResponseHandler.get when a paxos/transactional write fails on replicas with failure reason COORDINATOR_BEHIND. The counters show enough retriable failures that a retry (after the coordinator catches up on metadata) could still reach the consistency level, so the failure is surfaced as a retriable write failure rather than an immediate timeout.

Solutions

1. Retry the write; the coordinator behind on cluster metadata should converge
2. Check cluster connectivity so the coordinator can refresh its view of ring/replica state
3. If persistent, investigate why the coordinator's cluster metadata lags (CMS/gossip issues)

When it happens

Trigger: Thrown at src/java/org/apache/cassandra/service/AbstractWriteResponseHandler.java:179 when the library encounters an invalid state.

Common situations: See trigger scenarios.

AI-assisted analysis of apache/cassandra@88fd0f6a0e (2026-09-10). Data as JSON: /api/errors/b0cb390acb2f5d59. Report an issue: GitHub.

Appendix: source

Thrown at src/java/org/apache/cassandra/service/AbstractWriteResponseHandler.java:179

            int coordinatorBehindErrors = 0;
            for (RequestFailureReason reason : failureReasonByEndpoint.values())
            {
                if (reason == RETRY_ON_DIFFERENT_TRANSACTION_SYSTEM)
                    transactionRetryErrors++;
                if (reason == COORDINATOR_BEHIND)
                    coordinatorBehindErrors++;
            }
            int totalRetriableFailures = transactionRetryErrors + coordinatorBehindErrors;

            // Retrying might fix this
            if (candidateReplicaCount - failures + totalRetriableFailures  >= blockFor())
            {
                // Doesn't matter which we throw really but for clarity/metrics be specific
                // Retrying on the correct system might make this write succeed
                if (transactionRetryErrors > 0)
                    throw new RetryOnDifferentSystemException();
                if (coordinatorBehindErrors > 0)
                    throw new CoordinatorBehindException("Write request failed due to coordinator behind");
            }

            throw new WriteFailureException(replicaPlan.consistencyLevel(), ackCount(), blockFor(), writeType, getFailureReasonByEndpointMap());
        }

        if (replicaPlan.stillAppliesTo(ClusterMetadata.current()))
        {
            if (warningContext != null)
            {
                WriteWarningsSnapshot snapshot = warningContext.snapshot();
                if (!snapshot.isEmpty() && hintOnFailure != null)
                    CoordinatorWriteWarnings.update(hintOnFailure.get(), snapshot);
            }
        }
    }

    protected WriteWarningContext getWarningContext()
    {

View on GitHub (pinned to 88fd0f6a0e)