{"record":{"id":"1f50f25a78024a9c","repo":"apache/druid","slug":"query-s-timed-out-1f50f2","errorCode":null,"errorMessage":"Query [%s] timed out","messagePattern":"Query \\[(.+?)\\] timed out","errorType":"exception","errorClass":"QueryTimeoutException","httpStatus":null,"severity":"error","filePath":"processing/src/main/java/org/apache/druid/query/groupby/epinephelinae/GroupByMergingQueryRunner.java","lineNumber":399,"sourceCode":"\n      final List<AggregateResult> results = hasTimeout ? future.get(timeout, TimeUnit.MILLISECONDS) : future.get();\n\n      for (AggregateResult result : results) {\n        if (!result.isOk()) {\n          GuavaUtils.cancelAll(true, future, futures);\n          throw new ResourceLimitExceededException(result.getReason());\n        }\n      }\n    }\n    catch (InterruptedException | CancellationException e) {\n      log.noStackTrace().warn(e, \"Query interrupted, cancelling pending results for query [%s]\", query.getId());\n      GuavaUtils.cancelAll(true, future, futures);\n      throw new QueryInterruptedException(e);\n    }\n    catch (QueryTimeoutException | TimeoutException e) {\n      log.noStackTrace().warn(e, \"Query timeout, cancelling pending results for query [%s]\", query.getId());\n      GuavaUtils.cancelAll(true, future, futures);\n      throw new QueryTimeoutException(StringUtils.nonStrictFormat(\"Query [%s] timed out\", query.getId()));\n    }\n    catch (ExecutionException e) {\n      log.noStackTrace().warn(e, \"Query error, cancelling pending results for query [%s]\", query.getId());\n      GuavaUtils.cancelAll(true, future, futures);\n      Throwable cause = e.getCause();\n      // Nested per-segment future timeout\n      if (cause instanceof TimeoutException) {\n        throw new QueryTimeoutException(StringUtils.nonStrictFormat(\"Query timeout, cancelling pending results for query [%s]. Per-segment timeout exceeded.\", query.getId()));\n      }\n      throw new RuntimeException(e);\n    }\n  }\n}\n","sourceCodeStart":381,"sourceCodeEnd":413,"githubUrl":"https://github.com/apache/druid/blob/9b90983fd291f26935af934383ce360473179e4d/processing/src/main/java/org/apache/druid/query/groupby/epinephelinae/GroupByMergingQueryRunner.java#L381-L413","documentation":"waitForFutureCompletion waits on the merging query runner's futures for the configured query timeout. On QueryTimeoutException or TimeoutException it cancels the outstanding per-segment futures and throws QueryTimeoutException('Query [id] timed out'), surfacing the broker/timeout chain to the caller.","triggerScenarios":"A groupBy query's per-segment or overall futures do not complete within the configured timeout (query.getConfig().getTimeout() / PrioritizedExecutorTask queue wait), so waitForFutureCompletion (invoked from apply or make) cancels and throws.","commonSituations":"Heavy groupBy queries with huge cardinality; undersized processing thread pools; slow historicals (disk, GC); default 5-minute timeout exceeded; timeouts on large multi-interval scans.","solutions":["Raise the query timeout (timeout field in the query context / druid.query.defaultTimeout)","Optimize the query: narrow intervals, add filters, reduce dimensions/aggregators, enable query caching","Scale historicals (more cores/memory) or raise druid.processing.numThreads","Check for skewed/slow segments and broker queue wait times in metrics (query/time, query/wait/time)","Split the query into smaller time chunks and merge client-side"],"exampleFix":"// before\n{\"queryType\":\"groupBy\", \"intervals\":[\"2010/2026\"], ...} // exceeds default timeout\n// after\n{\"queryType\":\"groupBy\", \"intervals\":[\"2025/2026\"], \"context\":{\"timeout\":\"1800000\"}, ...} // narrower range + explicit timeout","handlingStrategy":"retry","validationCode":"long estMillis = estimateScanTime(query); // compare against configured timeout before submitting\nif (estMillis > timeoutMs) { narrowIntervalsOrRaiseTimeout(); }","typeGuard":null,"tryCatchPattern":"try { runQuery(query); } catch (QueryTimeoutException e) { if (e.getMessage().endsWith(\"timed out\")) { retryWithLargerTimeout(narrow(query)); } else { throw e; } }","preventionTips":["Set explicit query timeouts matching workload SLAs","Monitor query/wait/time metrics to size thread pools","Keep intervals narrow and enable caching for repeated queries"],"tags":["druid","groupby","timeout","distributed"],"backgroundTag":"request-timeout","analyzedSha":"9b90983fd291f26935af934383ce360473179e4d","analyzedAt":"2026-09-07T13:32:30.957Z","contentChangedAt":"2026-09-07T13:32:30.957Z","schemaVersion":2},"datasetVersion":"2026-09-14T05:17:10.506Z"}