{"record":{"id":"fdde292a9a8bc08d","repo":"apache/druid","slug":"query-s-url-s-timed-out","errorCode":null,"errorMessage":"Query[%s] url[%s] timed out.","messagePattern":"Query\\[(.+?)\\] url\\[(.+?)\\] timed out\\.","errorType":"exception","errorClass":"QueryTimeoutException","httpStatus":null,"severity":"error","filePath":"server/src/main/java/org/apache/druid/client/DirectDruidClient.java","lineNumber":228,"sourceCode":"          // channel while it is being wound down.\n          if (discard.get()) {\n            return true;\n          }\n          // Increment queuedByteCount before queueing the object, so queuedByteCount is at least as high as\n          // the actual number of queued bytes at any particular time.\n          final InputStreamHolder holder = InputStreamHolder.fromChannelBuffer(buffer, chunkNum);\n          final long currentQueuedByteCount = queuedByteCount.addAndGet(holder.getLength());\n          queue.put(holder);\n\n          // True if we should keep reading.\n          return !usingBackpressure || currentQueuedByteCount < maxQueuedBytes;\n        }\n\n        private InputStream dequeue() throws InterruptedException\n        {\n          final InputStreamHolder holder = queue.poll(checkQueryTimeout(), TimeUnit.MILLISECONDS);\n          if (holder == null) {\n            throw new QueryTimeoutException(StringUtils.nonStrictFormat(\"Query[%s] url[%s] timed out.\", query.getId(), url));\n          }\n\n          final long currentQueuedByteCount = queuedByteCount.addAndGet(-holder.getLength());\n          if (usingBackpressure && currentQueuedByteCount < maxQueuedBytes) {\n            long backPressureTime = Preconditions.checkNotNull(trafficCopRef.get(), \"No TrafficCop, how can this be?\")\n                                                 .resume(holder.getChunkNum());\n            channelSuspendedTime.addAndGet(backPressureTime);\n          }\n\n          return holder.getStream();\n        }\n\n        @Override\n        public ClientResponse<InputStream> handleResponse(HttpResponse response, TrafficCop trafficCop)\n        {\n          trafficCopRef.set(trafficCop);\n          checkQueryTimeout();\n          checkTotalBytesLimit(response.getContent().readableBytes());","sourceCodeStart":210,"sourceCodeEnd":246,"githubUrl":"https://github.com/apache/druid/blob/9b90983fd291f26935af934383ce360473179e4d/server/src/main/java/org/apache/druid/client/DirectDruidClient.java#L210-L246","documentation":"Thrown by DirectDruidClient's response-queue dequeue() when polling for the next response chunk times out (queue.poll(checkQueryTimeout()) returns null). It signals that the query's overall timeout (query.getContext().getTimeout() bounded by druid.broker.http.readTimeout) elapsed while waiting for data from the data node, wrapped as QueryTimeoutException.","triggerScenarios":"Issuing a query whose context timeout expires before the historical/data node returns the first or a subsequent response chunk; slow historical nodes; very large scans with small timeout values; overloaded data nodes delaying the HTTP response.","commonSituations":"Heavy group-by/scan queries exceeding a low druid.broker.http.readTimeout; historical nodes swapping or GC-paused; network stalls between broker and historical; default query timeout lowered in context.","solutions":["Increase the query timeout (context 'timeout' parameter) or the broker's druid.broker.http.readTimeout.","Optimize the query (add filters, reduce intervals scanned, tune group-by buffers) to run within the timeout.","Check historical node health (GC pauses, disk I/O, load) and scale if consistently slow.","Retry the query; transient data-node slowness may have caused the stall."],"exampleFix":"// before\nquery.getContext().put(\"timeout\", \"5000\");\n// after\nquery.getContext().put(\"timeout\", \"300000\");","handlingStrategy":"try-catch","validationCode":null,"typeGuard":null,"tryCatchPattern":"try {\n  return query.run(...);\n} catch (QueryTimeoutException e) {\n  // optionally retry with a larger timeout once\n  log.warn(\"Query timed out on %s: %s\", url, e.getMessage());\n  throw e;\n}","preventionTips":["Size the context 'timeout' to the query's worst-case runtime.","Keep druid.broker.http.readTimeout larger than the max query timeout.","Monitor historical node latency and GC pauses.","Alert on repeated query timeouts per datasource/interval."],"tags":["druid","broker","query-timeout","network"],"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"}