apache/cassandra · error · ReadFailureException

ReadFailureException

Error message

ReadFailureException(consistency=%s, received=%s, blockFor=%s, dataPresent=false, failureReasonByEndpoint=%s)

What it means

A ReadFailureException rethrown when the Paxos PROPOSE phase of a serial read fails with a WriteFailureException. It carries the received/blockFor counts and per-endpoint failure reasons from the underlying write, with dataPresent=false.

Solutions

Inspect failureReasonByEndpoint (in the driver exception) to find which replicas failed and why.
Repair or replace the failing replicas; run nodetool repair after they return.
Retry the serial read once replicas are healthy.
Ensure RF and consistency level allow quorum to proceed despite one unhealthy replica.

Example fix

// before
ResultSet rs = session.execute(lwtRead);
// after
try {
    ResultSet rs = session.execute(lwtRead);
} catch (AllNodesFailedException | ReadFailureException e) {
    // inspect e.getAllErrorMessage()/failure reasons, remediate replicas, retry
}

Defensive patterns

Strategy: try-catch

Validate before calling

int aliveReplicas = countHealthyReplicas(key, consistencyLevel);
if (aliveReplicas < consistencyLevel.blockFor(rf)) failFast("insufficient replicas for serial read");

Try / catch

catch (ReadFailureException e) {
    e.getFailuresMap().forEach((ep, reason) -> log.error("replica {} failed: {}", ep, reason));
    remediateAndRetry();
}

Prevention

Monitor per-endpoint write failures and repair/replace bad replicas quickly.
Keep RF high enough that quorum survives one unhealthy replica.
Alert on ReadFailure metrics by datacenter.
Run regular repairs so failed proposals leave no divergent state.

When it happens

Trigger: Same code path as the read timeout case, but replicas explicitly reported failure (e.g., node down, disk error, tombstone/limit breaches during the proposal write), so WriteFailureException is converted to ReadFailureException in the catch block.

Common situations: A replica crashed or was decommissioned mid-LWT operation; replicated writes failing below required blockFor due to hardware problems or overloaded replicas.

Understand the failure class

Background: "API error: {status}" and "HTTP 401/403/404/429/5xx" errors: non-2xx HTTP responses explained — this error's family across 27 libraries.

Related errors

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

Appendix: source

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

                // 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)
        {
            readMetrics.timeouts.mark();
            casReadMetrics.timeouts.mark();
            readMetricsForLevel(consistencyLevel).timeouts.mark();
            logRequestException(e, group.queries);

View on GitHub (pinned to 88fd0f6a0e)