{"record":{"id":"d3bae7d2dd291a19","repo":"apache/druid","slug":"url-s-timed-out","errorCode":null,"errorMessage":"url[%s] timed out","messagePattern":"url\\[(.+?)\\] timed out","errorType":"exception","errorClass":"QueryTimeoutException","httpStatus":null,"severity":"error","filePath":"server/src/main/java/org/apache/druid/client/JsonParserIterator.java","lineNumber":171,"sourceCode":"    long timeLeftMillis = timeoutAt - System.currentTimeMillis();\n    return checkTimeout(timeLeftMillis);\n  }\n\n  private boolean checkTimeout(long timeLeftMillis)\n  {\n    if (hasTimeout && timeLeftMillis < 1) {\n      return true;\n    }\n    return false;\n  }\n\n  private void init()\n  {\n    if (jp == null) {\n      try {\n        long timeLeftMillis = timeoutAt - System.currentTimeMillis();\n        if (checkTimeout(timeLeftMillis)) {\n          throw timeoutQuery();\n        }\n        InputStream is = hasTimeout ? future.get(timeLeftMillis, TimeUnit.MILLISECONDS) : future.get();\n\n        if (is != null) {\n          jp = objectMapper.getFactory().createParser(is);\n        } else if (checkTimeout()) {\n          throw timeoutQuery();\n        } else {\n          // The InputStream is null and we have not timed out, there might be multiple reasons why we could hit this\n          // condition, guess that we are hitting it because of scatter-gather bytes.  It would be better to be more\n          // explicit about why errors are happening than guessing, but this comment is being rewritten from a T-O-D-O,\n          // so the intent is just to document this better rather than do all of the logic to fix it.  If/when we get\n          // this exception thrown for other reasons, it would be great to document what other reasons this can happen.\n          throw ResourceLimitExceededException.withMessage(\n              \"Possibly max scatter-gather bytes limit reached while reading from url[%s].\",\n              url\n          );\n        }","sourceCodeStart":153,"sourceCodeEnd":189,"githubUrl":"https://github.com/apache/druid/blob/9b90983fd291f26935af934383ce360473179e4d/server/src/main/java/org/apache/druid/client/JsonParserIterator.java#L153-L189","documentation":"JsonParserIterator lazily opens the HTTP response for a broker-to-data-node query by calling future.get() with the remaining query timeout. If the deadline expires before the InputStream is available, init() throws this timeoutQuery() error naming the downstream URL. It signals that the data server did not start returning the query result within the allotted time.","triggerScenarios":"Calling hasNext() or next() on the iterator when future.get(timeLeftMillis) throws TimeoutException, i.e. the embedded HTTP future for url[%s] did not complete within the remaining query timeout budget.","commonSituations":"Slow or overloaded historical/realtime servers, large scan/groupBy queries exceeding druid.query.default.timeout or the per-query timeout, network latency between broker and data nodes, or a query with hasTimeout=true whose budget was mostly consumed before this segment's response was requested.","solutions":["Increase the query timeout (timeout SQL/HTTP query parameter or druid.query.default.timeout) and retry","Check the target data server's load and logs; scale out or tune its query processing threads","Reduce query cost (narrow intervals, add filters, limit granularity) so it completes within the timeout","Verify network connectivity/latency between broker and data nodes"],"exampleFix":"// before\nclient.query(\"SELECT * FROM wikiticker\"); // default timeout\n// after\nclient.query(\"SELECT * FROM wikiticker\").timeout(\"10m\"); // or set druid.query.default.timeout","handlingStrategy":"retry","validationCode":"// before issuing the query\nfinal long budgetMillis = 600_000;\nif (budgetMillis <= 0) { throw new IllegalArgumentException(\"query timeout must be positive\"); }\n// pass budgetMillis as the timeout parameter to the query","typeGuard":null,"tryCatchPattern":"try {\n  rows = iterator stream collect;\n} catch (QueryTimeoutException | TimeoutException e) {\n  log.warn(\"Query timed out; retrying with larger budget\");\n  // retry with increased timeout or back off\n}","preventionTips":["Set an explicit query timeout larger than expected worst-case runtime","Monitor historical/realtime server load and queue times","Keep broker and data node clocks synchronized so timeout budgets are computed correctly","Narrow query intervals and add filters to reduce runtime"],"tags":["timeout","http","query-execution","broker"],"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"}