apache/cassandra · error · CasWriteTimeoutException

CasWriteTimeoutException(writeType=%s, consistency=%s, recei

Error message

CasWriteTimeoutException(writeType=%s, consistency=%s, received=%s, blockFor=%s, contentions=%s)

What it means

legacyCas rethrows a CasWriteTimeoutException (with metrics marked) when the Paxos-based CAS write timed out before a quorum acknowledged. The exception carries writeType, consistency level, received/blockFor replica counts, and the number of contentions observed. It means the LWT did not commit within the write timeout.

Source

Thrown at src/java/org/apache/cassandra/service/StorageProxy.java:505

            return casResult(doPaxos(metadata,
                                     key,
                                     consistencyForPaxos,
                                     consistencyForCommit,
                                     consistencyForCommit,
                                     requestTime,
                                     casWriteMetrics,
                                     updateProposer));
        }
        catch (CasWriteUnknownResultException e)
        {
            casWriteMetrics.unknownResult.mark();
            throw e;
        }
        catch (CasWriteTimeoutException wte)
        {
            casWriteMetrics.timeouts.mark();
            writeMetricsForLevel(consistencyForPaxos).timeouts.mark();
            throw new CasWriteTimeoutException(wte.writeType, wte.consistency, wte.received, wte.blockFor, wte.contentions);
        }
        catch (ReadTimeoutException e)
        {
            casWriteMetrics.timeouts.mark();
            writeMetricsForLevel(consistencyForPaxos).timeouts.mark();
            throw e;
        }
        catch (ReadAbortException e)
        {
            casWriteMetrics.markAbort(e);
            writeMetricsForLevel(consistencyForPaxos).markAbort(e);
            throw e;
        }
        catch (WriteFailureException | ReadFailureException e)
        {
            casWriteMetrics.failures.mark();
            writeMetricsForLevel(consistencyForPaxos).failures.mark();
            throw e;

View on GitHub (pinned to 88fd0f6a0e)

Solutions

Retry the CAS operation; timeout under contention is safe to retry (the transaction did not commit).
Increase write_request_timeout_in_ms if timeouts occur due to latency, not contention.
Reduce contention (rate-limit writes to the contested key) or shard work across more partition keys.
Check replica availability; ensure quorum of replicas is up and reachable.

Example fix

// before
session.execute("UPDATE stock SET n = n - 1 WHERE sku = ? IF n > 0", sku);
// after: catch and retry with backoff
try {
    session.execute("UPDATE stock SET n = n - 1 WHERE sku = ? IF n > 0", sku);
} catch (CasWriteTimeoutException e) {
    Thread.sleep(50 * e.getContentions());
    // retry the same LWT
}

Defensive patterns

Strategy: retry

Try / catch

try {
    session.execute(lwt);
} catch (CasWriteTimeoutException e) {
    Thread.sleep(Math.min(1000L, 20L * e.getContentions()));
    // safe to retry: the transaction did not commit
}

Prevention

Minimize writers contending on the same LWT partition.
Tune write_request_timeout_in_ms for your latency profile (cross-DC needs more).
Alert on casWriteMetrics.timeouts rate.

When it happens

Trigger: Executing a lightweight transaction via legacyCas when proposePaxos/commitPaxos raises WriteTimeoutException, converted to CasWriteTimeoutException with the original received/blockFor values; typically under contention or with slow replicas.

Common situations: LWT under heavy contention on a hot row; one replica down so quorum can't be met within write_request_timeout_in_ms; cross-DC LWT with high latency.

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

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