What causes "ReadTimeoutException" in apache/cassandra?

Run a full/primary-range nodetool repair to resynchronize replicas

apache/cassandra · error · ReadTimeoutException

ReadTimeoutException

Error message

ReadTimeoutException

What it means

BlockingReadRepairs.createRepairMutation throws ReadTimeoutException when repair mutations are constructed for a read-repair but the awaited acknowledgments time out, unless suppressException is set. The client gets a ReadTimeoutException with received = blockFor-1, indicating the read-repair write phase could not complete for the required consistency level.

Solutions

Run a full/primary-range nodetool repair to resynchronize replicas
Raise write_request_timeout_in_ms and range/request timeouts if repairs are data-heavy
Investigate replica failure reasons (dropped mutations, overload) via nodetool tpstats and logs
Suppress/repair asynchronously if the workload shouldn't fail reads on repair timeouts (version-dependent behavior)

Example fix

// before
// reads fail while replicas diverge
// after
$ nodetool repair -pr ks tbl   # then reads stop triggering blocking repairs

Defensive patterns

Strategy: retry

Validate before calling

// Detect stale replicas proactively: alert on repair age (last repair > gc_grace) before issuing strict-CL reads

Try / catch

try {
  return session.execute(query);
} catch (e) {
  if (e instanceof ReadTimeoutException && /read-repair/i.test(String(e.message || ''))) {
    return retryWithBackoff(query, 1); // transient repair timeout
  }
  throw e;
}

Prevention

Run incremental or full repairs on schedule to keep replicas consistent
Investigate failure reasons logged with the timeout (node down, dropped mutations)
Tune write_request_timeout_in_ms for tombstone-heavy tables
Watch digest-mismatch/read-repair metrics as an early-warning signal

When it happens

Trigger: Digest-mismatched read at a consistency level; repair mutations are sent to stale replicas; awaited acks time out; if the caller did not suppress the exception (background/speculative repairs), it is rethrown to the coordinator thread.

Common situations: Divergent replicas after node replacement or long downtime; tombstone-heavy rows making repair writes exceed timeouts; low consistency levels combined with frequently stale replicas.

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

Appendix: source

Thrown at src/java/org/apache/cassandra/service/reads/repair/BlockingReadRepairs.java:91

                             MAX_MUTATION_SIZE,
                             metadata,
                             metadata.partitionKeyType.getString(key.getKey()),
                             destination);
            }
            else
            {
                logger.warn("Encountered an oversized ({}/{}) read repair mutation for table {}, key {}, node {}",
                            e.mutationSize,
                            MAX_MUTATION_SIZE,
                            metadata,
                            metadata.partitionKeyType.getString(key.getKey()),
                            destination);

                if (!suppressException)
                {
                    int blockFor = consistency.blockFor(keyspace.getReplicationStrategy());
                    Tracing.trace("Timed out while read-repairing after receiving all {} data and digest responses", blockFor);
                    throw new ReadTimeoutException(consistency, blockFor - 1, blockFor, true);
                }
            }
            return null;
        }
    }
}

View on GitHub (pinned to 88fd0f6a0e)