apache/cassandra · warning · QueryCancelledException

QueryCancelledException(readCommand)

Error message

QueryCancelledException(readCommand)

What it means

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.

Source

Thrown at src/java/org/apache/cassandra/index/sai/QueryContext.java:91

    public QueryContext(ReadCommand readCommand, long executionQuotaMs)
    {
        this.readCommand = readCommand;
        executionQuotaNano = TimeUnit.MILLISECONDS.toNanos(executionQuotaMs);
        queryStartTimeNanos = Clock.Global.nanoTime();
    }

    public long totalQueryTimeNs()
    {
        return Clock.Global.nanoTime() - queryStartTimeNanos;
    }

    public void checkpoint()
    {
        if (totalQueryTimeNs() >= executionQuotaNano && !DISABLE_TIMEOUT)
        {
            queryTimedOut = true;
            throw new QueryCancelledException(readCommand);
        }
    }

    public int limit()
    {
        return readCommand.limits().count();
    }
}

View on GitHub (pinned to 88fd0f6a0e)

Solutions

1. Increase the SAI query timeout/quota configuration (e.g. sai_coordinator_query_timeout)
2. Make the query more selective (add predicates, limit partitions scanned)
3. Reduce cluster load or add capacity; run compaction to lower SSTable count
4. Retry the query — transient load spikes can push it past the deadline

Example fix

// before
SELECT * FROM sensor_data WHERE reading > 0; // unbounded, times out
// after
SELECT * FROM sensor_data WHERE reading > 0 AND day = '2026-09-09' LIMIT 1000;

// ensure the query is bounded before issuing:
// add selective predicates and LIMIT so expected scan time fits the quota

try { rs = session.execute(saiQuery); } catch (QueryCancelledException e) { /* backoff and retry with tighter predicates or increased timeout */ }

When it happens

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

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

Understand the failure class

Background: Request timed out: what client-side request timeouts mean across libraries (Request timed out, TIMED_OUT, APITimeoutError) — this error's family across 39 libraries.

Related errors

• Unsupported expression:
• Unsupported expression during index query:
• Reversed queries are not supported.
• The 'key' column can only be used in an equality query for t
• Range queries are not supported. Please provide both a keysp

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