{"record":{"id":"f9ba09003361774c","repo":"apache/cassandra","slug":"replica-filtering-protection-has-cached-over-d-ro","errorCode":null,"errorMessage":"Replica filtering protection has cached over %d rows during query %s. (See 'cached_replica_rows_fail_threshold' in cassandra.yaml.)","messagePattern":"Replica filtering protection has cached over (.+?) rows during query (.+?)\\. \\(See 'cached_replica_rows_fail_threshold' in cassandra\\.yaml\\.\\)","errorType":"exception","errorClass":"OverloadedException","httpStatus":null,"severity":"error","filePath":"src/java/org/apache/cassandra/service/reads/ReplicaFilteringProtection.java","lineNumber":335,"sourceCode":"     */\n    UnfilteredPartitionIterators.MergeListener mergeController()\n    {\n        return mergeListener;\n    }\n\n    private void incrementCachedRows()\n    {\n        currentRowsCached++;\n\n        if (currentRowsCached == cachedRowsFailThreshold + 1)\n        {\n            String message = String.format(\"Replica filtering protection has cached over %d rows during query %s. \" +\n                                           \"(See 'cached_replica_rows_fail_threshold' in cassandra.yaml.)\",\n                                           cachedRowsFailThreshold, command.toCQLString());\n\n            logger.error(message);\n            Tracing.trace(message);\n            throw new OverloadedException(message);\n        }\n        else if (currentRowsCached == cachedRowsWarnThreshold + 1 && !hitWarningThreshold)\n        {\n            hitWarningThreshold = true;\n\n            String message = String.format(\"Replica filtering protection has cached over %d rows during query %s. \" +\n                                           \"(See 'cached_replica_rows_warn_threshold' in cassandra.yaml.)\",\n                                           cachedRowsWarnThreshold, command.toCQLString());\n\n            ClientWarn.instance.warn(message);\n            oneMinuteLogger.warn(message);\n            Tracing.trace(message);\n        }\n    }\n\n    private void releaseCachedRows(int count)\n    {\n        maxRowsCached = Math.max(maxRowsCached, currentRowsCached);","sourceCodeStart":317,"sourceCodeEnd":353,"githubUrl":"https://github.com/apache/cassandra/blob/88fd0f6a0eaed8943f05ac9e8f947882b8ddc8f1/src/java/org/apache/cassandra/service/reads/ReplicaFilteringProtection.java#L317-L353","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","solutions":["Make the query more selective (add partition key restrictions or use a secondary index) so fewer rows are cached","Raise cached_replica_rows_fail_threshold (and cached_replica_rows_warn_threshold) in cassandra.yaml if large scans are legitimate","Enable/raise replicas_per_module_draft or reduce page size to limit per-page cached rows","Review the CQL string in the message to identify the offending query and rewrite it with a materialized view or denormalized table"],"exampleFix":"// before (cassandra.yaml)\ncached_replica_rows_fail_threshold: 200000\n// after\ncached_replica_rows_fail_threshold: 2000000","handlingStrategy":"try-catch","validationCode":"// Estimate scanned rows before issuing the query\n// if partition size estimates (nodetool tablestats) exceed cached_replica_rows_fail_threshold, rewrite the query first","typeGuard":null,"tryCatchPattern":"try {\n  session.execute(filteringQuery);\n} catch (e) {\n  if (e instanceof OverloadedException || /cached over \\d+ rows/.test(String(e.message))) {\n    logger.warn('Replica filtering protection threshold hit; refining query or raising threshold', e);\n    // fall back to a more selective query or scheduled rewrite\n  } else throw e;\n}","preventionTips":["Avoid ALLOW FILTERING queries over huge partitions; add partition-key constraints","Monitor cached_rows warnings in logs before they escalate to failures","Tune cached_replica_rows_warn/fail_thresholds to your workload's real scan sizes","Precompute filtered views (materialized views or denormalized tables) for hot filtered queries"],"tags":["read-path","filtering","memory","overload"],"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"}