{"record":{"id":"3866529c73179a83","repo":"apache/cassandra","slug":"querycancelledexception-readcommand","errorCode":null,"errorMessage":"QueryCancelledException(readCommand)","messagePattern":"QueryCancelledException\\(readCommand\\)","errorType":"exception","errorClass":"QueryCancelledException","httpStatus":null,"severity":"warning","filePath":"src/java/org/apache/cassandra/index/sai/QueryContext.java","lineNumber":91,"sourceCode":"\n    public QueryContext(ReadCommand readCommand, long executionQuotaMs)\n    {\n        this.readCommand = readCommand;\n        executionQuotaNano = TimeUnit.MILLISECONDS.toNanos(executionQuotaMs);\n        queryStartTimeNanos = Clock.Global.nanoTime();\n    }\n\n    public long totalQueryTimeNs()\n    {\n        return Clock.Global.nanoTime() - queryStartTimeNanos;\n    }\n\n    public void checkpoint()\n    {\n        if (totalQueryTimeNs() >= executionQuotaNano && !DISABLE_TIMEOUT)\n        {\n            queryTimedOut = true;\n            throw new QueryCancelledException(readCommand);\n        }\n    }\n\n    public int limit()\n    {\n        return readCommand.limits().count();\n    }\n}\n","sourceCodeStart":73,"sourceCodeEnd":100,"githubUrl":"https://github.com/apache/cassandra/blob/88fd0f6a0eaed8943f05ac9e8f947882b8ddc8f1/src/java/org/apache/cassandra/index/sai/QueryContext.java#L73-L100","documentation":"QueryContext.checkpoint throws QueryCancelledException(readCommand) when a SAI query's total execution time exceeds the configured execution quota (executionQuotaNs) unless timeouts are disabled. It is thrown from periodic checkpoints so long-running SAI queries are cancelled cooperatively rather than blocking indefinitely.","triggerScenarios":"SAI query scanning many index partitions/sstables such that query time exceeds the quota (default from sai_coordinator_query_timeout / related execution quota settings); checkpoints called from query build() detect the overrun.","commonSituations":"Large partition counts, many SSTables or high read concurrency making index queries slow; poorly selective SAI queries (low-cardinality predicates); heavy cluster load raising latency past the timeout.","solutions":["Increase the SAI query timeout/quota configuration (e.g. sai_coordinator_query_timeout)","Make the query more selective (add predicates, limit partitions scanned)","Reduce cluster load or add capacity; run compaction to lower SSTable count","Retry the query — transient load spikes can push it past the deadline"],"exampleFix":"// before\nSELECT * FROM sensor_data WHERE reading > 0; // unbounded, times out\n// after\nSELECT * FROM sensor_data WHERE reading > 0 AND day = '2026-09-09' LIMIT 1000;","handlingStrategy":"retry","validationCode":"// ensure the query is bounded before issuing:\n// add selective predicates and LIMIT so expected scan time fits the quota","typeGuard":null,"tryCatchPattern":"try { rs = session.execute(saiQuery); } catch (QueryCancelledException e) { /* backoff and retry with tighter predicates or increased timeout */ }","preventionTips":["Set realistic sai_coordinator_query_timeout for your data volume","Avoid low-selectivity SAI predicates (e.g. boolean flags) on large tables","Monitor query latency and SSTable counts; keep compaction current"],"tags":["cassandra","sai","timeout","query"],"backgroundTag":"request-timeout","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"}