apache/cassandra · error · ReadTimeoutException

ReadTimeoutException

Error message

ReadTimeoutException

What it means

During replica filtering protection, when a replica digest mismatch requires refetching data, a source ReadTimeoutException is deliberately rethrown as a new ReadTimeoutException with blockFor-1 received out of blockFor — reporting that the coordinator could not get enough responses with the extra fetch. It surfaces to the client as a read timeout even though the original timeout happened on an internal refetch.

Solutions

1. Increase read_request_timeout_in_ms in cassandra.yaml if refetches legitimately take long
2. Rewrite the query to avoid heavy filtering so digest-mismatch refetches are rare
3. Check the health/latency of the replicas involved (nodetool tpstats, GC logs) and fix slow nodes
4. Retry the query; if reproducible, reduce page size to bound per-request work

Example fix

// before
cassandra.yaml: read_request_timeout_in_ms: 5000
// after
cassandra.yaml: read_request_timeout_in_ms: 10000

// Pre-check replica latency before expensive filtered reads
// shell: nodetool tpstats | grep 'ReadStage' && nodetool netstats — skip/defer if backlog is high

try {
  return session.execute(query);
} catch (e) {
  if (e instanceof ReadTimeoutException && e.received >= e.blockFor - 1) {
    // likely read-repair/filtering refetch timeout: one retry with backoff
    return retryWithBackoff(query, 1);
  }
  throw e;
}

When it happens

Trigger: A filtered read with digest mismatches triggers fetchFromSource; that internal read command times out (replica slow, GC pause, overloaded), so the coordinator converts it into a client-visible ReadTimeoutException at one less response than the block-for.

Common situations: Large filtering queries hammering replicas; one replica consistently slow so repair fetches time out; tight timeouts (read_request_timeout) with big partitions under ALLOW FILTERING.

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
• Addresses differ: !=
• Already released
• ANN ordering by vector requires all restricted column(s) to…

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

Appendix: source

Thrown at src/java/org/apache/cassandra/service/reads/ReplicaFilteringProtection.java:647

            SinglePartitionReadCommand cmd = SinglePartitionReadCommand.create(command.metadata(),
                                                                               command.nowInSec(),
                                                                               command.columnFilter(),
                                                                               RowFilter.none(),
                                                                               DataLimits.NONE,
                                                                               key,
                                                                               filter);

            ReplicaPlan.ForTokenRead replicaPlan = ReplicaPlans.forSingleReplicaRead(keyspace, key.getToken(), source);

            try
            {
                return executeReadCommand(cmd, source, ReplicaPlan.shared(replicaPlan));
            }
            catch (ReadTimeoutException e)
            {
                int blockFor = consistency.blockFor(replicaPlan.replicationStrategy());
                throw new ReadTimeoutException(consistency, blockFor - 1, blockFor, true);
            }
            catch (UnavailableException e)
            {
                int blockFor = consistency.blockFor(replicaPlan.replicationStrategy());
                throw UnavailableException.create(consistency, blockFor, blockFor - 1);
            }
        }
    }
}

View on GitHub (pinned to 88fd0f6a0e)