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_warn_threshold' in cassandra.yaml.)

What it means

ReplicaFilteringProtection caches rows on the coordinator when replica-side filtering cannot fully resolve the query (e.g. filtering with page-size limits). When the number of cached rows exceeds `cached_replica_rows_warn_threshold`, this warning is emitted to the client (ClientWarn), the server log, and the trace — indicating the coordinator is buffering many rows and memory pressure is possible.

Source

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

        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);
        currentRowsCached -= count;
    }

    /**
     * Returns the protected results for the specified replica. These are generated fetching the extra rows and merging
     * them with the cached original filtered results for that replica.
     *
     * @param merged the first iteration partitions, that should have been read used with the {@link #mergeController()}
     * @param source the source
     * @return the protected results for the specified replica

View on GitHub (pinned to 88fd0f6a0e)

Solutions

Rewrite the query/data model to avoid ALLOW FILTERING (denormalize or use a table designed for the access pattern)
Increase page size (LIMIT / paging state) so fewer paging rounds trigger protection caching, or reduce result set size
Raise cached_replica_rows_warn_threshold in cassandra.yaml if the buffering is acceptable and only the warning is unwanted
Monitor coordinator heap; if near limits, restrict the query with partition key constraints

Example fix

// before
SELECT * FROM users WHERE country = 'US' ALLOW FILTERING;
// after
SELECT * FROM users_by_country WHERE country = 'US';

Defensive patterns

Strategy: validation

Validate before calling

// client-side pre-check before issuing a filtering query
if (query.hasAllowFiltering() && !query.hasPartitionKeyConstraint())
    logger.warn("Query '{}' will trigger replica filtering protection; consider a denormalized table", cql);

Try / catch

try {
    rs = session.execute(query);
} catch (DriverException e) {
    // warnings are non-fatal; inspect Warnings on the ResultSet
    for (String w : rs.getExecutionInfo().getWarnings())
        if (w.contains("cached over")) planQueryRewrite(w);
}

Prevention

Avoid ALLOW FILTERING on wide tables; model tables for the query
Enable and monitor cached_replica_rows metrics
Set realistic page sizes and cached_replica_rows_warn_threshold

When it happens

Trigger: Executing a SELECT with ALLOW FILTERING (or secondary-index queries) across multiple paging cycles where per-page filtering protection caches more rows than cached_replica_rows_warn_threshold in a single query.

Common situations: Large ALLOW FILTERING queries over wide partitions; too-small page size with big result sets; threshold left at default while running analytics-style filtering 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

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