apache/cassandra · error · LocalReadSizeTooLargeException

LocalReadSizeTooLargeException

Error message

LocalReadSizeTooLargeException

What it means

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.

Source

Thrown at src/java/org/apache/cassandra/db/ReadCommand.java:823

            @Override
            protected DeletionTime applyToDeletion(DeletionTime deletionTime)
            {
                addSize(deletionTime.unsharedHeapSize());
                return deletionTime;
            }

            private void addSize(long size)
            {
                this.sizeInBytes += size;
                if (failBytes != -1 && this.sizeInBytes >= failBytes)
                {
                    String msg = String.format("Query %s attempted to read %d bytes but max allowed is %s; query aborted  (see local_read_size_fail_threshold)",
                                               ReadCommand.this.toCQLString(), this.sizeInBytes, failThreshold);
                    Tracing.trace(msg);
                    MessageParams.remove(ParamType.LOCAL_READ_SIZE_WARN);
                    MessageParams.add(ParamType.LOCAL_READ_SIZE_FAIL, this.sizeInBytes);
                    throw new LocalReadSizeTooLargeException(msg);
                }
                else if (warnBytes != -1 && this.sizeInBytes >= warnBytes)
                {
                    MessageParams.add(ParamType.LOCAL_READ_SIZE_WARN, this.sizeInBytes);
                }
            }

            @Override
            protected void onClose()
            {
                ColumnFamilyStore cfs = Schema.instance.getColumnFamilyStoreInstance(metadata().id);
                if (cfs != null)
                    cfs.metric.localReadSize.update(sizeInBytes);
            }
        }

        iterator = Transformation.apply(iterator, new QuerySizeTracking());
        return iterator;

View on GitHub (pinned to 88fd0f6a0e)

Solutions

1. Add LIMIT or narrow the partition key/IN clause so the coordinator reads fewer bytes.
2. Use paging (driver fetchSize) and iterate instead of one huge result set.
3. Raise local_read_size_fail_threshold (and warn threshold) in cassandra.yaml if the workload legitimately reads that much (memory permitting).
4. Model data so single queries touch bounded partitions.

Example fix

// before
ResultSet rs = session.execute("SELECT payload FROM events WHERE day = ?", today); // reads all partitions for the day
// after
ResultSet rs = session.execute("SELECT payload FROM events WHERE day = ? LIMIT 10000", today); // or iterate pages

// Bound result size at the query level:
String q = baseQuery + (hasPartitionKey ? "" : " LIMIT " + maxRows);
session.execute(q);

try { rs = session.execute(query); } catch (DriverException e) {
    if (e.getMessage() != null && e.getMessage().contains("local_read_size")) { narrowQueryAndRetry(); } else throw e;
}

When it happens

Trigger: 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.

Common situations: 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.

Understand the failure class

Background: payload too large / request exceeds maximum size: why libraries cap bytes and how to fix oversize payloads — this error's family across 50 libraries.

Related errors

• TombstoneOverwhelmingException
• MutationExceededMaxSizeException
• QueryCancelledException
• Replica filtering protection has cached over %d rows during
• TombstoneAbortException

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