{"record":{"id":"157e6c280f56e30c","repo":"apache/druid","slug":"query-s-timed-out","errorCode":null,"errorMessage":"Query [%s] timed out","messagePattern":"Query \\[(.+?)\\] timed out","errorType":"exception","errorClass":"QueryTimeoutException","httpStatus":null,"severity":"warning","filePath":"processing/src/main/java/org/apache/druid/query/ChainedExecutionQueryRunner.java","lineNumber":175,"sourceCode":"            queryWatcher.registerQueryFuture(query, future);\n\n            try {\n              return new MergeIterable<>(\n                  context.hasTimeout() ?\n                      future.get(context.getTimeout(), TimeUnit.MILLISECONDS) :\n                      future.get(),\n                  ordering.nullsFirst()\n              ).iterator();\n            }\n            catch (CancellationException | InterruptedException 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 (TimeoutException | QueryTimeoutException 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              Throwables.throwIfUnchecked(cause);\n              throw new RuntimeException(cause);\n            }\n          }\n\n          @Override\n          public void cleanup(Iterator<T> tIterator)\n          {\n","sourceCodeStart":157,"sourceCodeEnd":193,"githubUrl":"https://github.com/apache/druid/blob/9b90983fd291f26935af934383ce360473179e4d/processing/src/main/java/org/apache/druid/query/ChainedExecutionQueryRunner.java#L157-L193","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","solutions":["Raise the query context timeout, e.g. {\"timeout\": 300000} in the query JSON","Reduce query cost: narrow intervals, add filters, pre-aggregate, or switch to a cheaper engine (timeseries instead of groupBy where possible)","Scale historicals (more threads/heap) or check for slow disks/GC pauses slowing segment processing","Check per-segment timeout settings (druid.query.perSegmentTimeout / context) if nested per-segment timeouts are in play"],"exampleFix":"// before\nPOST /druid/v2 {\"queryType\":\"groupBy\", ...} // default timeout too small\n// after\nPOST /druid/v2 {\"queryType\":\"groupBy\", ..., \"context\":{\"timeout\": 300000}}","handlingStrategy":"try-catch","validationCode":"// set an explicit timeout before submitting\nMap<String, Object> ctx = new HashMap<>();\nctx.put(\"timeout\", 300000);\n// sanity-check expected scan cost: num rows x segments via datasource metadata","typeGuard":null,"tryCatchPattern":"try {\n  results = client.query(queryJson);\n} catch (QueryTimeoutException e) {\n  // retry with larger timeout or cheaper query\n}","preventionTips":["Set realistic context timeouts for long-running queries","Narrow query intervals and add selective filters","Monitor historical load and scale before timeouts become routine","Prefer aggregated datasources for dashboards hitting wide ranges"],"tags":["druid","query-timeout","performance","futures"],"backgroundTag":"request-timeout","analyzedSha":"9b90983fd291f26935af934383ce360473179e4d","analyzedAt":"2026-09-07T13:32:30.957Z","contentChangedAt":"2026-09-07T13:32:30.957Z","schemaVersion":2},"datasetVersion":"2026-09-17T15:17:12.973Z"}