apache/cassandra · error · WriteTimeoutException

WriteTimeoutException

Error message

WriteTimeoutException

What it means

AbstractPaxosCallback.await blocks until enough CAS responses arrive; if the latch times out within DatabaseDescriptor.getWriteRpcTimeout, it throws WriteTimeoutException(WriteType.CAS) reporting achieved vs required responses. This means not enough paxos replicas replied to the CAS write in time.

Solutions

1. Check that enough replicas for the chosen CL are up and responsive (nodetool status)
2. Increase write_rpc_timeout in cassandra.yaml if paxos rounds are legitimately slow under load
3. Retry the CAS operation; paxos timeouts are often transient under contention
4. Reduce LTX contention (fewer contending clients per row) or investigate slow replicas via tracing

Example fix

// before
cassandra.yaml: write_rpc_timeout: 2000
// after
cassandra.yaml: write_rpc_timeout: 10000
$ nodetool reloadseeds && restart node (config change requires restart)

// check quorum availability before issuing a CAS
int alive = replicasFor(key).stream().filter(fd::isAlive).count();
if (alive < requiredFor(consistencyLevel)) throw new UnavailableException(consistencyLevel, requiredFor(consistencyLevel), alive);

try { session.execute(casStatement); }
catch (WriteTimeoutException e) { if (e.writeType() == WriteType.CAS) { backoff(); retryOnce(); } else throw e; }

When it happens

Trigger: CAS (INSERT ... IF NOT EXISTS / UPDATE ... IF conditions) at a consistency level whose required replica count did not respond within write_rpc_timeout; slow replicas, GC pauses, or down/unreachable replicas.

Common situations: Lightweight transactions under heavy load, one or more replicas down while using QUORUM/SERIAL, network issues in a multi-DC setup, or paxos contention causing slow rounds.

Understand the failure class

Background: Request timed out: what client-side request timeouts mean across libraries (Request timed out, TIMED_OUT, APITimeoutError) — this error's family across 39 libraries.

• Timeouts: ETIMEDOUT, deadlines, and hung requests — what actually expires when a request times out.

Related errors

• Operation timed out
• ReadTimeoutException
• WRITE_TIMEOUT
• Cannot perform LWT operation as there is more than one
• CasWriteTimeoutException

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

Appendix: source

Thrown at src/java/org/apache/cassandra/service/paxos/v1/AbstractPaxosCallback.java:61

        this.consistency = consistency;
        latch = newCountDownLatch(targets);
        this.requestTime = requestTime;
    }

    public int getResponseCount()
    {
        return targets - latch.count();
    }

    public void await() throws WriteTimeoutException
    {
        try
        {
            long now = Clock.Global.nanoTime();
            long timeout = requestTime.computeTimeout(now, DatabaseDescriptor.getWriteRpcTimeout(NANOSECONDS));

            if (!latch.await(timeout, NANOSECONDS))
                throw new WriteTimeoutException(WriteType.CAS, consistency, getResponseCount(), targets);
        }
        catch (InterruptedException e)
        {
            throw new UncheckedInterruptedException(e);
        }
    }
}

View on GitHub (pinned to 88fd0f6a0e)