apache/cassandra · error · CasWriteTimeoutException

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

Error message

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

What it means

beginAndRepairPaxos converts a WriteTimeoutException observed while preparing/repairing the Paxos ballot into a CasWriteTimeoutException with writeType=CAS, preserving the original received/blockFor. Per CASSANDRA-8672 the write type is reported as CAS because the failure occurs during Paxos preparation, not a normal write.

Source

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

                // mean we lost messages), we pro-actively "repair" those nodes, and retry.
                Iterable<InetAddressAndPort> missingMRC = summary.replicasMissingMostRecentCommit(metadata);
                if (Iterables.size(missingMRC) > 0)
                {
                    Tracing.trace("Repairing replicas that missed the most recent commit");
                    sendCommit(mostRecent, consistencyForPaxos, missingMRC);
                    // TODO: provided commits don't invalid the prepare we just did above (which they don't), we could just wait
                    // for all the missingMRC to acknowledge this commit and then move on with proposing our value. But that means
                    // adding the ability to have commitPaxos block, which is exactly CASSANDRA-5442 will do. So once we have that
                    // latter ticket, we can pass CL.ALL to the commit above and remove the 'continue'.
                    continue;
                }

                return new PaxosBallotAndContention(ballot, contentions);
            }
            catch (WriteTimeoutException e)
            {
                // We're still doing preparation for the paxos rounds, so we want to use the CAS (see CASSANDRA-8672)
                throw new CasWriteTimeoutException(WriteType.CAS, e.consistency, e.received, e.blockFor, contentions);
            }
        }

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

    /**
     * Unlike commitPaxos, this does not wait for replies
     */
    private static void sendCommit(Commit commit, ConsistencyLevel consistencyForPaxos, Iterable<InetAddressAndPort> replicas)
    {
        Message<Commit> message = Message.out(PAXOS_COMMIT_REQ, commit);
        for (InetAddressAndPort target : replicas)
            MessagingService.instance().send(message, target);
    }

    private static PrepareCallback preparePaxos(Commit toPrepare, ReplicaPlan.ForPaxosWrite replicaPlan, Dispatcher.RequestTime requestTime)
    throws WriteTimeoutException

View on GitHub (pinned to 88fd0f6a0e)

Solutions

  1. Retry the operation; a new coordinator will complete the stale ballot and proceed.
  2. Increase cas_contention_timeout_in_ms and write_request_timeout_in_ms.
  3. Investigate replicas with GC pauses or network issues that slow the prepare rounds.
  4. Reduce LWT concurrency on the partition to avoid repeated ballot contention.

Example fix

// before
ConsistencyLevel cl = ConsistencyLevel.SERIAL; // cross-dc LWT, slow prepares
// after
ConsistencyLevel cl = ConsistencyLevel.LOCAL_SERIAL; // localize paxos rounds
Defensive patterns

Strategy: retry

Try / catch

try {
    session.execute(lwt);
} catch (CasWriteTimeoutException e) {
    // prepare-phase timeout; safe to retry with a fresh ballot
    retryWithBackoff(lwt);
}

Prevention

When it happens

Trigger: During a CAS, the initial Paxos prepare/retry loop fails because a replica with a promised in-progress ballot times out on the prepare round; called from the pair()/execute path.

Common situations: A previous LWT coordinator died mid-ballot leaving an in-progress Paxos state that must be completed; slow replicas during the prepare phase; repeated contention increments.

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.

Related errors

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