{"record":{"id":"c9ad0af194659b84","repo":"apache/cassandra","slug":"localreadsizetoolargeexception","errorCode":null,"errorMessage":"LocalReadSizeTooLargeException","messagePattern":"LocalReadSizeTooLargeException","errorType":"exception","errorClass":"LocalReadSizeTooLargeException","httpStatus":null,"severity":"error","filePath":"src/java/org/apache/cassandra/db/ReadCommand.java","lineNumber":823,"sourceCode":"\n            @Override\n            protected DeletionTime applyToDeletion(DeletionTime deletionTime)\n            {\n                addSize(deletionTime.unsharedHeapSize());\n                return deletionTime;\n            }\n\n            private void addSize(long size)\n            {\n                this.sizeInBytes += size;\n                if (failBytes != -1 && this.sizeInBytes >= failBytes)\n                {\n                    String msg = String.format(\"Query %s attempted to read %d bytes but max allowed is %s; query aborted  (see local_read_size_fail_threshold)\",\n                                               ReadCommand.this.toCQLString(), this.sizeInBytes, failThreshold);\n                    Tracing.trace(msg);\n                    MessageParams.remove(ParamType.LOCAL_READ_SIZE_WARN);\n                    MessageParams.add(ParamType.LOCAL_READ_SIZE_FAIL, this.sizeInBytes);\n                    throw new LocalReadSizeTooLargeException(msg);\n                }\n                else if (warnBytes != -1 && this.sizeInBytes >= warnBytes)\n                {\n                    MessageParams.add(ParamType.LOCAL_READ_SIZE_WARN, this.sizeInBytes);\n                }\n            }\n\n            @Override\n            protected void onClose()\n            {\n                ColumnFamilyStore cfs = Schema.instance.getColumnFamilyStoreInstance(metadata().id);\n                if (cfs != null)\n                    cfs.metric.localReadSize.update(sizeInBytes);\n            }\n        }\n\n        iterator = Transformation.apply(iterator, new QuerySizeTracking());\n        return iterator;","sourceCodeStart":805,"sourceCodeEnd":841,"githubUrl":"https://github.com/apache/cassandra/blob/88fd0f6a0eaed8943f05ac9e8f947882b8ddc8f1/src/java/org/apache/cassandra/db/ReadCommand.java#L805-L841","documentation":"ReadCommand's local read-size guardian aborts a query with LocalReadSizeTooLargeException when the estimated bytes to be read locally on this node exceed local_read_size_fail_threshold (default: fail at 128MB via cassandra.yaml local_read_size settings). It protects coordinators from queries that would materialize enormous amounts of data in memory.","triggerScenarios":"Executing a query whose per-coordinator estimated read size (rows × avg cell size, from counter/metrics-derived heuristics) crosses the fail threshold — typically large IN clauses, SELECT without LIMIT over wide partitions, or full scans of wide rows.","commonSituations":"Analytics-style ad hoc queries against OLTP tables; missing LIMIT on wide-partition reads; environments where average value sizes grew after a schema change, pushing formerly fine queries over the threshold.","solutions":["Add LIMIT or narrow the partition key/IN clause so the coordinator reads fewer bytes.","Use paging (driver fetchSize) and iterate instead of one huge result set.","Raise local_read_size_fail_threshold (and warn threshold) in cassandra.yaml if the workload legitimately reads that much (memory permitting).","Model data so single queries touch bounded partitions."],"exampleFix":"// before\nResultSet rs = session.execute(\"SELECT payload FROM events WHERE day = ?\", today); // reads all partitions for the day\n// after\nResultSet rs = session.execute(\"SELECT payload FROM events WHERE day = ? LIMIT 10000\", today); // or iterate pages","handlingStrategy":"validation","validationCode":"// Bound result size at the query level:\nString q = baseQuery + (hasPartitionKey ? \"\" : \" LIMIT \" + maxRows);\nsession.execute(q);","typeGuard":null,"tryCatchPattern":"try { rs = session.execute(query); } catch (DriverException e) {\n    if (e.getMessage() != null && e.getMessage().contains(\"local_read_size\")) { narrowQueryAndRetry(); } else throw e;\n}","preventionTips":["Always add LIMIT to wide or unbounded queries.","Use driver paging (fetchSize) and iterate result sets.","Keep partition sizes bounded (avoid very wide partitions).","Know your local_read_size warn/fail thresholds and monitor warnings."],"tags":["read-path","memory-protection","query-aborted","payload-too-large"],"backgroundTag":"payload-too-large","analyzedSha":"88fd0f6a0eaed8943f05ac9e8f947882b8ddc8f1","analyzedAt":"2026-09-10T07:29:22.284Z","contentChangedAt":"2026-09-10T07:29:22.284Z","schemaVersion":2},"datasetVersion":"2026-09-14T16:17:12.679Z"}