{"record":{"id":"37d9a739c86e560b","repo":"apache/cassandra","slug":"readtimeoutexception-37d9a7","errorCode":null,"errorMessage":"ReadTimeoutException","messagePattern":"ReadTimeoutException","errorType":"exception","errorClass":"ReadTimeoutException","httpStatus":null,"severity":"error","filePath":"src/java/org/apache/cassandra/service/reads/ReplicaFilteringProtection.java","lineNumber":647,"sourceCode":"\n            SinglePartitionReadCommand cmd = SinglePartitionReadCommand.create(command.metadata(),\n                                                                               command.nowInSec(),\n                                                                               command.columnFilter(),\n                                                                               RowFilter.none(),\n                                                                               DataLimits.NONE,\n                                                                               key,\n                                                                               filter);\n\n            ReplicaPlan.ForTokenRead replicaPlan = ReplicaPlans.forSingleReplicaRead(keyspace, key.getToken(), source);\n\n            try\n            {\n                return executeReadCommand(cmd, source, ReplicaPlan.shared(replicaPlan));\n            }\n            catch (ReadTimeoutException e)\n            {\n                int blockFor = consistency.blockFor(replicaPlan.replicationStrategy());\n                throw new ReadTimeoutException(consistency, blockFor - 1, blockFor, true);\n            }\n            catch (UnavailableException e)\n            {\n                int blockFor = consistency.blockFor(replicaPlan.replicationStrategy());\n                throw UnavailableException.create(consistency, blockFor, blockFor - 1);\n            }\n        }\n    }\n}\n","sourceCodeStart":629,"sourceCodeEnd":657,"githubUrl":"https://github.com/apache/cassandra/blob/88fd0f6a0eaed8943f05ac9e8f947882b8ddc8f1/src/java/org/apache/cassandra/service/reads/ReplicaFilteringProtection.java#L629-L657","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","solutions":["Increase read_request_timeout_in_ms in cassandra.yaml if refetches legitimately take long","Rewrite the query to avoid heavy filtering so digest-mismatch refetches are rare","Check the health/latency of the replicas involved (nodetool tpstats, GC logs) and fix slow nodes","Retry the query; if reproducible, reduce page size to bound per-request work"],"exampleFix":"// before\ncassandra.yaml: read_request_timeout_in_ms: 5000\n// after\ncassandra.yaml: read_request_timeout_in_ms: 10000","handlingStrategy":"retry","validationCode":"// Pre-check replica latency before expensive filtered reads\n// shell: nodetool tpstats | grep 'ReadStage' && nodetool netstats — skip/defer if backlog is high","typeGuard":null,"tryCatchPattern":"try {\n  return session.execute(query);\n} catch (e) {\n  if (e instanceof ReadTimeoutException && e.received >= e.blockFor - 1) {\n    // likely read-repair/filtering refetch timeout: one retry with backoff\n    return retryWithBackoff(query, 1);\n  }\n  throw e;\n}","preventionTips":["Keep read_request_timeout_in_ms generous for filtering-heavy workloads","Fix chronically slow replicas (GC, disk) promptly","Reduce page size for heavy filtered queries","Track digest-mismatch rates; frequent repairs indicate replica drift needing nodetool repair"],"tags":["read-timeout","filtering","read-repair","network"],"backgroundTag":"request-timeout","analyzedSha":"88fd0f6a0eaed8943f05ac9e8f947882b8ddc8f1","analyzedAt":"2026-09-10T07:29:22.284Z","contentChangedAt":"2026-09-10T07:29:22.284Z","schemaVersion":2},"datasetVersion":"2026-09-17T15:17:12.973Z"}