apache/druid · error · QueryInterruptedException

Truncated response context

Truncated response context

Error message

Serialized response context exceeds the max size[%s]

What it means

When pushing results (QueryResultPusher), the serialized response context header is capped by druid.broker.http maxResponseContextHeaderSize. If the serialized context exceeds the limit and shouldFailOnTruncatedResponseContext is true, a QueryInterruptedException wrapping TruncatedResponseContextException is thrown instead of silently truncating.

Solutions

Increase druid.broker.http maxResponseContextHeaderSize (and maxResponseContextBufferSize)
Reduce context payload: remove large custom context values from queries
Set shouldFailOnTruncatedResponseContext=false to truncate instead of failing (with awareness that context may be lost)
Upgrade/flatten very deeply nested queries that inflate the context

Example fix

// before
runtime.properties:
  druid.broker.http.maxResponseContextHeaderSize=1000
// after
  druid.broker.http.maxResponseContextHeaderSize=8192

Defensive patterns

Strategy: validation

Validate before calling

int serializedSize = ResponseContext.serializeSize(context);
if (serializedSize > maxResponseContextHeaderSize) {
  throw new IllegalArgumentException("Trim response context; " + serializedSize
      + " exceeds " + maxResponseContextHeaderSize);
}

Try / catch

try {
  pusher.run();
} catch (QueryInterruptedException e) {
  if (e.getErrorCode().equals("Truncated response context")) {
    log.error("Response context too large; increase maxResponseContextHeaderSize or trim context");
  }
  throw e;
}

Prevention

Keep query context values small; never pass bulk data via context
Increase maxResponseContextHeaderSize for clusters running deep SQL/nested queries
Understand shouldFailOnTruncatedResponseContext before enabling it
Monitor context header sizes in high-fanout broker setups

When it happens

Trigger: A query response context larger than maxResponseContextHeaderSize (e.g. many chained subqueries accumulating context keys, large cached/tag data in context) combined with shouldFailOnTruncatedResponseContext=true.

Common situations: Deeply nested SQL queries generating large response context payloads; clients stuffing large custom context values into native queries; strict-failure clusters with legacy big context headers.

Understand the failure class

Background: payload too large / request exceeds maximum size: why libraries cap bytes and how to fix oversize payloads — this error's family across 50 libraries.

Related errors

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

Appendix: source

Thrown at server/src/main/java/org/apache/druid/server/QueryResultPusher.java:502

            jsonMapper,
            responseContextConfig.getMaxResponseContextHeaderSize()
        );
      }
      catch (JsonProcessingException e) {
        log.info(e, "Problem serializing to JSON!?");
        serializationResult = new ResponseContext.SerializationResult("Could not serialize", "Could not serialize");
      }

      if (serializationResult.isTruncated()) {
        final String logToPrint = StringUtils.format(
            "Response Context truncated for id [%s]. Full context is [%s].",
            queryId,
            serializationResult.getFullResult()
        );

        if (responseContextConfig.shouldFailOnTruncatedResponseContext()) {
          log.error(logToPrint);
          throw new QueryInterruptedException(
              new TruncatedResponseContextException(
                  "Serialized response context exceeds the max size[%s]",
                  responseContextConfig.getMaxResponseContextHeaderSize()
              ),
              selfNode.getHostAndPortToUse()
          );
        } else {
          log.warn(logToPrint);
        }
      }
      response.setHeader(QueryResource.HEADER_RESPONSE_CONTEXT, serializationResult.getResult());
    }

    @Override
    @Nullable
    public Response accumulate(Response retVal, Object in)
    {
      if (!initialized) {

View on GitHub (pinned to 9b90983fd2)