apache/cassandra · error · OverloadedException

Replica filtering protection has cached over %d rows during

Error message

Replica filtering protection has cached over %d rows during query %s. (See 'cached_replica_rows_fail_threshold' in cassandra.yaml.)

What it means

Thrown by ReplicaFilteringProtection.incrementCachedRows when the number of rows cached by replica-side filtering protection for a single query exceeds cached_replica_rows_fail_threshold. Replica filtering protection caches rows from replicas to reconcile filtering mismatches; an unbounded cache means the query is scanning/caching far more rows than expected and could exhaust coordinator memory.

Source

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

     */
    UnfilteredPartitionIterators.MergeListener mergeController()
    {
        return mergeListener;
    }

    private void incrementCachedRows()
    {
        currentRowsCached++;

        if (currentRowsCached == cachedRowsFailThreshold + 1)
        {
            String message = String.format("Replica filtering protection has cached over %d rows during query %s. " +
                                           "(See 'cached_replica_rows_fail_threshold' in cassandra.yaml.)",
                                           cachedRowsFailThreshold, command.toCQLString());

            logger.error(message);
            Tracing.trace(message);
            throw new OverloadedException(message);
        }
        else if (currentRowsCached == cachedRowsWarnThreshold + 1 && !hitWarningThreshold)
        {
            hitWarningThreshold = true;

            String message = String.format("Replica filtering protection has cached over %d rows during query %s. " +
                                           "(See 'cached_replica_rows_warn_threshold' in cassandra.yaml.)",
                                           cachedRowsWarnThreshold, command.toCQLString());

            ClientWarn.instance.warn(message);
            oneMinuteLogger.warn(message);
            Tracing.trace(message);
        }
    }

    private void releaseCachedRows(int count)
    {
        maxRowsCached = Math.max(maxRowsCached, currentRowsCached);

View on GitHub (pinned to 88fd0f6a0e)

Solutions

1. Make the query more selective (add partition key restrictions or use a secondary index) so fewer rows are cached
2. Raise cached_replica_rows_fail_threshold (and cached_replica_rows_warn_threshold) in cassandra.yaml if large scans are legitimate
3. Enable/raise replicas_per_module_draft or reduce page size to limit per-page cached rows
4. Review the CQL string in the message to identify the offending query and rewrite it with a materialized view or denormalized table

Example fix

// before (cassandra.yaml)
cached_replica_rows_fail_threshold: 200000
// after
cached_replica_rows_fail_threshold: 2000000

// Estimate scanned rows before issuing the query
// if partition size estimates (nodetool tablestats) exceed cached_replica_rows_fail_threshold, rewrite the query first

try {
  session.execute(filteringQuery);
} catch (e) {
  if (e instanceof OverloadedException || /cached over \d+ rows/.test(String(e.message))) {
    logger.warn('Replica filtering protection threshold hit; refining query or raising threshold', e);
    // fall back to a more selective query or scheduled rewrite
  } else throw e;
}

When it happens

Trigger: Running a large ALLOW FILTERING / secondary-index query where replicas return many non-matching rows that must be cached to merge digests, exceeding the configured cached_replica_rows_fail_threshold from cassandra.yaml.

Common situations: Badly selective static/partition-key filters forcing full partition scans; tables with very large partitions combined with filtering queries; thresholds left at defaults for workloads with legitimately large filtered scans.

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

• Replica filtering protection has cached over %d rows during
• memtable_heap_space must be positive, but was ${conf.memtabl
• repair_session_space must be > 0, but was ${conf.repair_sess
• Cannot set repair_session_space to < 1 mebibyte
• %s must be positive value <= %dB, but was %dB

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