apache/cassandra · error · CasWriteTimeoutException

CasWriteTimeoutException(writeType=CAS, consistency=%s, rece

Error message

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

What it means

After the Paxos rounds in doPaxos exhaust their deadline without success, Cassandra throws a synthetic CasWriteTimeoutException with received=0 and writeType=CAS, indicating the overall Paxos attempt budget expired rather than a single RPC timing out. contentions reports how often concurrent ballots were seen.

Source

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

        catch (CasWriteTimeoutException e)
        {
            // Might be thrown by beginRepairAndPaxos. In that case, any contention that happened within the method and
            // led up to the timeout was not accounted in our local 'contentions' variable and we add it now so it the
            // contention recorded in the finally is correct.
            contentions += e.contentions;
            throw e;
        }
        catch (WriteTimeoutException e)
        {
            // Might be thrown by proposePaxos or commitPaxos
            throw new CasWriteTimeoutException(e.writeType, e.consistency, e.received, e.blockFor, contentions);
        }
        finally
        {
            recordCasContention(metadata, key, casMetrics, contentions);
        }

        throw new CasWriteTimeoutException(WriteType.CAS, consistencyForPaxos, 0, consistencyForPaxos.blockFor(latestRs), contentions);
    }

    /**
     * begin a Paxos session by sending a prepare request and completing any in-progress requests seen in the replies
     *
     * @return the Paxos ballot promised by the replicas if no in-progress requests were seen and a quorum of
     * nodes have seen the mostRecentCommit.  Otherwise, return null.
     */
    private static PaxosBallotAndContention beginAndRepairPaxos(Dispatcher.RequestTime requestTime,
                                                                DecoratedKey key,
                                                                TableMetadata metadata,
                                                                ReplicaPlan.ForPaxosWrite paxosPlan,
                                                                ConsistencyLevel consistencyForPaxos,
                                                                ConsistencyLevel consistencyForCommit,
                                                                CASClientRequestMetrics casMetrics)
    throws WriteTimeoutException, WriteFailureException
    {
        long timeoutNanos = DatabaseDescriptor.getCasContentionTimeout(NANOSECONDS);

View on GitHub (pinned to 88fd0f6a0e)

Solutions

Increase cas_contention_timeout_in_ms so the Paxos loop gets more time to win.
Redesign the hot-key workload: avoid many writers contending on one LWT row (batch, queue sharding, or move to a non-LWT strategy).
Retry with exponential backoff; the transaction did not apply.
Upgrade away from legacy Paxos to the newer Paxos implementation / Accord-based paths if available.

Example fix

// before
cassandra.yaml: cas_contention_timeout_in_ms: 1000
// after
cassandra.yaml: cas_contention_timeout_in_ms: 10000

Defensive patterns

Strategy: retry

Try / catch

try {
    session.execute(lwt);
} catch (CasWriteTimeoutException e) {
    if (e.getContentions() > 0) backoffExponentially(e.getContentions());
    retry(lwt);
}

Prevention

Size cas_contention_timeout_in_ms above worst-case Paxos round-trip plus retries.
Avoid hot-row CAS loops; shard keys or redesign to reduce write contention.
Watch recordCasContention metrics / contention logs per partition.

When it happens

Trigger: A CAS whose Paxos loop (beginAndRepairPaxos plus propose/commit) could not complete within cas_contention_timeout_in_ms — typically sustained contention on the same partition — so doPaxos falls out of the loop and throws with received=0.

Common situations: Many clients performing LWTs on one hot row (queue-head patterns); long-running in-progress Paxos ballots requiring repeated repair rounds; cas_contention_timeout too low for the workload.

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/ec1d97b8d7f3a057. Report an issue: GitHub.