apache/druid · warning · QueryTimeoutException

Query [ ] timed out

Error message

Query [%s] timed out

What it means

Thrown when waiting for per-segment futures in ChainedExecutionQueryRunner.make() hits TimeoutException or QueryTimeoutException. All pending segment futures are cancelled and a QueryTimeoutException with "Query [%s] timed out" is raised, meaning the query exceeded its allotted time budget.

Solutions

1. Raise the query context timeout, e.g. {"timeout": 300000} in the query JSON
2. Reduce query cost: narrow intervals, add filters, pre-aggregate, or switch to a cheaper engine (timeseries instead of groupBy where possible)
3. Scale historicals (more threads/heap) or check for slow disks/GC pauses slowing segment processing
4. Check per-segment timeout settings (druid.query.perSegmentTimeout / context) if nested per-segment timeouts are in play

Example fix

// before
POST /druid/v2 {"queryType":"groupBy", ...} // default timeout too small
// after
POST /druid/v2 {"queryType":"groupBy", ..., "context":{"timeout": 300000}}

// set an explicit timeout before submitting
Map<String, Object> ctx = new HashMap<>();
ctx.put("timeout", 300000);
// sanity-check expected scan cost: num rows x segments via datasource metadata

try {
  results = client.query(queryJson);
} catch (QueryTimeoutException e) {
  // retry with larger timeout or cheaper query
}

When it happens

Trigger: Query context 'timeout' value exceeded while awaiting segment results; per-segment futures not completing within the deadline (slow scans, heavy groupBy, overloaded historicals); default server timeout (druid.server.http.timeout / query timeout defaults) hit on large queries.

Common situations: Large range scans over many segments on under-provisioned historicals; expensive groupBy/topN with high cardinality; misconfigured or too-small timeout in query context; clusters under load causing segment futures to queue behind other queries.

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.

• Timeouts: ETIMEDOUT, deadlines, and hung requests — what actually expires when a request times out.

Related errors

• Query timeout, cancelling pending results for query
• Query[ ] url[ ] timed out.
• A-Not-B requires at least 1 sketch
• Access-Check-Result
• Action [ ] failed for worker [ ] with status ( )

AI-assisted analysis of apache/druid@9b90983fd2 (2026-09-07). Data as JSON: /api/errors/157e6c280f56e30c. Report an issue: GitHub.

Appendix: source

Thrown at processing/src/main/java/org/apache/druid/query/ChainedExecutionQueryRunner.java:175

            queryWatcher.registerQueryFuture(query, future);

            try {
              return new MergeIterable<>(
                  context.hasTimeout() ?
                      future.get(context.getTimeout(), TimeUnit.MILLISECONDS) :
                      future.get(),
                  ordering.nullsFirst()
              ).iterator();
            }
            catch (CancellationException | InterruptedException e) {
              log.noStackTrace().warn(e, "Query interrupted, cancelling pending results for query [%s]", query.getId());
              GuavaUtils.cancelAll(true, future, futures);
              throw new QueryInterruptedException(e);
            }
            catch (TimeoutException | QueryTimeoutException e) {
              log.noStackTrace().warn(e, "Query timeout, cancelling pending results for query [%s]", query.getId());
              GuavaUtils.cancelAll(true, future, futures);
              throw new QueryTimeoutException(StringUtils.nonStrictFormat("Query [%s] timed out", query.getId()));
            }
            catch (ExecutionException e) {
              log.noStackTrace().warn(e, "Query error, cancelling pending results for query [%s]", query.getId());
              GuavaUtils.cancelAll(true, future, futures);
              Throwable cause = e.getCause();
              // Nested per-segment future timeout
              if (cause instanceof TimeoutException) {
                throw new QueryTimeoutException(StringUtils.nonStrictFormat("Query timeout, cancelling pending results for query [%s]. Per-segment timeout exceeded.", query.getId()));
              }
              Throwables.throwIfUnchecked(cause);
              throw new RuntimeException(cause);
            }
          }

          @Override
          public void cleanup(Iterator<T> tIterator)
          {

View on GitHub (pinned to 9b90983fd2)