apache/cassandra · warning · QueryCancelledException

QueryCancelledException

Error message

QueryCancelledException

What it means

ReadCommand's ClientRequest / execution controller checks an approximate-time deadline; if the command has been aborted (e.g. request timeout elapsed or a client disconnected and abort() was called), the iterator is stopped and QueryCancelledException is thrown. It converts an externally requested cancellation into a distinct, catchable failure instead of returning partial results.

Source

Thrown at src/java/org/apache/cassandra/db/ReadCommand.java:892

            maybeCancel();
            return row;
        }

        private void maybeCancel()
        {
            /*
             * The value returned by approxTime.now() is updated only every
             * {@link org.apache.cassandra.utils.MonotonicClock.SampledClock.CHECK_INTERVAL_MS}, by default 2 millis.
             * Since MonitorableImpl relies on approxTime, we don't need to check unless the approximate time has elapsed.
             */
            if (lastCheckedAt == approxTime.now())
                return;
            lastCheckedAt = approxTime.now();

            if (isAborted())
            {
                stop();
                throw new QueryCancelledException(ReadCommand.this);
            }
        }
    }

    private UnfilteredPartitionIterator withQueryCancellation(UnfilteredPartitionIterator iter)
    {
        return Transformation.apply(iter, new QueryCancellationChecker());
    }

    /**
     *  A transformation used for simulating slow queries by tests.
     */
    @VisibleForTesting
    private static class DelayInjector extends Transformation<UnfilteredRowIterator>
    {
        @Override
        protected UnfilteredRowIterator applyToPartition(UnfilteredRowIterator partition)
        {

View on GitHub (pinned to 88fd0f6a0e)

Solutions

  1. Increase the client-side read/request timeout or reduce query size (LIMIT, paging).
  2. Retry with exponential backoff if the query was cancelled due to overload; investigate underlying read latency.
  3. Address root causes: run compaction, check tombstone counts, avoid unbounded queries.
  4. Ensure driver consistency: don't close sessions/cluster while queries are pending.

Example fix

// before
clusterBuilder.withSocketOptions(opts.setReadTimeoutMillis(2000)); // too low for scans
// after
clusterBuilder.withSocketOptions(opts.setReadTimeoutMillis(20000)); // plus paged queries with LIMIT
Defensive patterns

Strategy: retry

Validate before calling

// Set driver read timeout comfortably above p99 query latency measured in monitoring.

Try / catch

try { rs = session.execute(query); } catch (DriverException e) {
    if (isCancellation(e)) { if (attempt < MAX_RETRY) retryWithBackoff(); else fail(); } else throw e;
}

Prevention

When it happens

Trigger: A read that exceeds the client's request timeout (driver/socket read timeout) or whose client disconnects, so the coordinator aborts the command; the next iterator advance notices isAborted() and throws.

Common situations: Slow reads (huge scans, tombstone storms) exceeding the driver's read timeout; application shutting down/cancelling futures while a query is in flight; load-shedding under overload.

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

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