apache/cassandra · error · ReadTimeoutException

ReadTimeoutException(consistency=%s, received=0, blockFor=%s

Error message

ReadTimeoutException(consistency=%s, received=0, blockFor=%s, dataPresent=false)

What it means

A ReadTimeoutException (received=0, dataPresent=false) rethrown when the Paxos PROPOSE phase of a serial read times out as a WriteTimeoutException. It is translated so LWT callers see a read-side timeout consistent with the operation type.

Source

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

                    !Paxos.isLinearizable()
                    ? ballot -> null
                    : ballot -> Pair.create(PartitionUpdate.emptyUpdate(metadata, key), null);
                // When replaying, we commit at quorum/local quorum, as we want to be sure the following read (done at
                // quorum/local_quorum) sees any replayed updates. Our own update is however empty, and those don't even
                // get committed due to an optimiation described in doPaxos/beingRepairAndPaxos, so the commit
                // consistency is irrelevant (we use ANY just to emphasis that we don't wait on our commit).
                doPaxos(metadata,
                        key,
                        consistencyLevel,
                        consistencyForReplayCommitsOrFetch,
                        ConsistencyLevel.ANY,
                        requestTime,
                        casReadMetrics,
                        updateProposer);
            }
            catch (WriteTimeoutException e)
            {
                throw new ReadTimeoutException(consistencyLevel, 0, blockForRead, false);
            }
            catch (WriteFailureException e)
            {
                throw new ReadFailureException(consistencyLevel, e.received, e.blockFor, false, e.failureReasonByEndpoint);
            }

            return serialReadResult(fetchRows(group.queries, consistencyForReplayCommitsOrFetch, ReadCoordinator.DEFAULT, requestTime));
        }
        catch (UnavailableException e)
        {
            readMetrics.unavailables.mark();
            casReadMetrics.unavailables.mark();
            readMetricsForLevel(consistencyLevel).unavailables.mark();
            logRequestException(e, group.queries);
            throw e;
        }
        catch (ReadTimeoutException e)
        {

View on GitHub (pinned to 88fd0f6a0e)

Solutions

Retry the serial read; Paxos timeouts on contention are usually transient.
Reduce contention on the partition (spread hot keys, fewer concurrent LWTs per row).
Increase write_request_timeout and cas_contention_timeout in cassandra.yaml if the cluster is consistently slow.
Check replica health and GC pauses that inflate Paxos round latency.

Example fix

// before
ResultSet rs = session.execute(serialRead);
// after
try {
    ResultSet rs = session.execute(serialRead);
} catch (ReadTimeoutException | com.datastax.driver.core.exceptions.ReadTimeoutException e) {
    // retry with backoff; 0 of blockFor acked
}

Defensive patterns

Strategy: retry

Validate before calling

long contention = currentLwtInFlightFor(key);
if (contention > threshold) yieldOrQueueInsteadOfLwt(key);

Try / catch

catch (ReadTimeoutException e) {
    if (e.getCode() == 0x1200 && !e.wasDataPresent()) {
        sleep(jitter(backoff));
        return retrySerialRead(); // Paxos timeouts on contention are transient
    }
    throw e;
}

Prevention

Minimize concurrent LWTs on the same partition.
Tune write_request_timeout and cas_contention_timeout for your replica latency.
Watch Paxos metrics (cas read/write contention) and alert on spikes.
Keep replicas healthy; investigate GC pauses and disk latency.

When it happens

Trigger: legacyReadWithPaxos/ReadPhase BEGIN/PROPOSE: the Paxos proposal write does not reach blockForRead replicas within write timeout (cas_contention_timeout / write_request_timeout exceeded), so the catch block converts WriteTimeoutException to ReadTimeoutException(consistency, 0, blockForRead, false).

Common situations: Contended LWT rows (many CAS proposals on the same partition), slow replicas, write_request_timeout too low, node stalls during Paxos 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

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