grpc/grpc-java · error · IllegalArgumentException

Header value length exceeds maximum allowed length:

Error message

Header value length exceeds maximum allowed length: 

What it means

applyHeaderMutations validates header values produced by an xDS ext_proc (ExternalProcessing) server before applying them to the call. If the raw byte length of a header value exceeds HeaderValueValidationUtils.MAX_HEADER_LENGTH, an IllegalArgumentException with the offending size is thrown, since gRPC/HTTP2 headers must stay within size limits.

Source

Thrown at xds/src/main/java/io/grpc/xds/internal/extproc/ExternalProcessorUtil.java:287

      HeaderMutator mutator)
      throws HeaderMutationDisallowedException {
    if (metadata == null) {
      return;
    }
    ImmutableList.Builder<HeaderValueOption> headersToModify = ImmutableList.builder();
    for (io.envoyproxy.envoy.config.core.v3.HeaderValueOption protoOption
        : mutation.getSetHeadersList()) {
      io.envoyproxy.envoy.config.core.v3.HeaderValue protoHeader = protoOption.getHeader();
      String key = protoHeader.getKey();
      HeaderValueValidationUtils.validateHeaderKey(key);

      ByteString rawBytes = protoHeader.getRawValue();
      if (rawBytes.isEmpty()) {
        rawBytes = ByteString.copyFromUtf8(protoHeader.getValue());
      }

      if (rawBytes.size() > HeaderValueValidationUtils.MAX_HEADER_LENGTH) {
        throw new IllegalArgumentException(
            "Header value length exceeds maximum allowed length: " + rawBytes.size());
      }

      HeaderValue headerValue;
      if (key.endsWith(Metadata.BINARY_HEADER_SUFFIX)) {
        byte[] decodedBytes = BaseEncoding.base64().decode(rawBytes.toStringUtf8());
        headerValue = HeaderValue.create(key, ByteString.copyFrom(decodedBytes));
      } else {
        headerValue = HeaderValue.create(key, rawBytes.toStringUtf8());
      }
      headersToModify.add(HeaderValueOption.create(
          headerValue,
          HeaderValueOption.HeaderAppendAction.valueOf(protoOption.getAppendAction().name())));
    }

    ImmutableList.Builder<String> headersToRemove = ImmutableList.builder();
    for (String headerToRemove : mutation.getRemoveHeadersList()) {
      HeaderValueValidationUtils.validateHeaderKey(headerToRemove);

View on GitHub (pinned to 64daddc1f3)

Solutions

1. Fix or reconfigure the ext_proc server so mutated header values stay under MAX_HEADER_LENGTH
2. Move large payloads out of headers into the request body or trailers metadata
3. Truncate or hash oversized values before returning them from the processor
4. Wrap applyHeaderMutations in try-catch to fail the RPC gracefully instead of propagating

Example fix

// ext_proc response before
headers.add(HeaderValue.newBuilder().setKey("x-trace").setValue(largeJson).build())
// after
String digest = BaseEncoding.base64().encode(hash(largeJson.getBytes(UTF_8)));
headers.add(HeaderValue.newBuilder().setKey("x-trace-digest").setValue(digest).build())

if (rawBytes.size() > HeaderValueValidationUtils.MAX_HEADER_LENGTH) { dropOrTruncate(header); }

null

try { ExternalProcessorUtil.applyHeaderMutations(...); }
catch (IllegalArgumentException e) { log.warn("Oversized header value rejected", e); failRpcWithStatus(ResourceExhausted); }

When it happens

Trigger: An ExternalProcessor's header mutation response (set/append/add headers) contains a value whose bytes exceed MAX_HEADER_LENGTH when applyHeaderMutations is called.

Common situations: ext_proc middleware returning large tokens/JSON blobs in a header; binary headers whose base64-decoded payload is oversized; misconfigured ext_proc server echoing an entire request body into a header.

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

• Invalid header key:
• Invalid initial metadata header: ${key}
• Invalid initial metadata header: " + key
• Not implemented
• unsupported ExtAuthz service type: only grpc_service is supp

AI-assisted analysis of grpc/grpc-java@64daddc1f3 (2026-09-08). Data as JSON: /api/errors/751ec4b0a328171d. Report an issue: GitHub.