apache/cassandra · error · ReadTimeoutException

ReadTimeoutException

Error message

ReadTimeoutException

What it means

After a digest mismatch, the read executor waits for read-repair responses at CL.ALL; awaitReadRepair throws ReadTimeoutException if the repair responses don't arrive in time. Per CASSANDRA-7947 the exception reports the read-quorum counts, so the reported consistency/counts reflect the repair command, not the original read CL.

Solutions

1. Check replica health and network; restart or replace unresponsive replicas
2. Increase read_rpc_timeout in cassandra.yaml if repairs are slow but progressing
3. Run nodetool repair to restore consistency so fewer digests mismatch
4. Investigate why replicas diverge (dropped mutations, failed writes) via logs

Example fix

// before
cassandra.yaml: read_rpc_timeout: 5000
// after
cassandra.yaml: read_rpc_timeout: 15000
(restart required)

// preflight: ensure all read replicas are alive for the chosen CL
long alive = replicaPlan.readReplicas().stream().filter(fd::isAlive).count();
if (alive < replicaPlan.readQuorum()) throw new UnavailableException(cl, replicaPlan.readQuorum(), (int) alive);

try { rs = session.execute(readQuery); }
catch (ReadTimeoutException e) { backoff(); retryWithLowerCLorFail(); }

When it happens

Trigger: Digest mismatch triggers read repair, but at least one replica holding the repair response fails to reply within read_rpc_timeout; slow/hung replicas, GC pauses, or network issues during the repair round.

Common situations: Reads on tables with frequent inconsistencies (hinted handoff backlog, failing replica), timeouts under heavy read load, multi-DC latency during repair.

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

• ReadTimeoutException
• ReadTimeoutException
• Attempting to load denylist and not enough nodes are…
• Auth check after connection closed
• Cannot achieve consistency level

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

Appendix: source

Thrown at src/java/org/apache/cassandra/service/reads/AbstractReadExecutor.java:476

            }
        }
    }

    public void awaitReadRepair() throws ReadTimeoutException
    {
        try
        {
            readRepair.awaitReads();
        }
        catch (ReadTimeoutException e)
        {
            if (Tracing.isTracing())
                Tracing.trace("Timed out waiting on digest mismatch repair requests");
            else
                logger.trace("Timed out waiting on digest mismatch repair requests");
            // the caught exception here will have CL.ALL from the repair command,
            // not whatever CL the initial command was at (CASSANDRA-7947)
            throw new ReadTimeoutException(replicaPlan().consistencyLevel(), handler.replicaPlan().readQuorum() - 1, handler.replicaPlan().readQuorum(), true);
        }
    }

    boolean isDone()
    {
        return result != null;
    }

    public void maybeSendAdditionalDataRequests()
    {
        if (isDone())
            return;

        readRepair.maybeSendAdditionalReads();
    }

    public PartitionIterator getResult() throws ReadFailureException, ReadTimeoutException
    {

View on GitHub (pinned to 88fd0f6a0e)