{"record":{"id":"751ec4b0a328171d","repo":"grpc/grpc-java","slug":"header-value-length-exceeds-maximum-allowed-length","errorCode":null,"errorMessage":"Header value length exceeds maximum allowed length: ","messagePattern":"Header value length exceeds maximum allowed length: ","errorType":"validation","errorClass":"IllegalArgumentException","httpStatus":null,"severity":"error","filePath":"xds/src/main/java/io/grpc/xds/internal/extproc/ExternalProcessorUtil.java","lineNumber":287,"sourceCode":"      HeaderMutator mutator)\n      throws HeaderMutationDisallowedException {\n    if (metadata == null) {\n      return;\n    }\n    ImmutableList.Builder<HeaderValueOption> headersToModify = ImmutableList.builder();\n    for (io.envoyproxy.envoy.config.core.v3.HeaderValueOption protoOption\n        : mutation.getSetHeadersList()) {\n      io.envoyproxy.envoy.config.core.v3.HeaderValue protoHeader = protoOption.getHeader();\n      String key = protoHeader.getKey();\n      HeaderValueValidationUtils.validateHeaderKey(key);\n\n      ByteString rawBytes = protoHeader.getRawValue();\n      if (rawBytes.isEmpty()) {\n        rawBytes = ByteString.copyFromUtf8(protoHeader.getValue());\n      }\n\n      if (rawBytes.size() > HeaderValueValidationUtils.MAX_HEADER_LENGTH) {\n        throw new IllegalArgumentException(\n            \"Header value length exceeds maximum allowed length: \" + rawBytes.size());\n      }\n\n      HeaderValue headerValue;\n      if (key.endsWith(Metadata.BINARY_HEADER_SUFFIX)) {\n        byte[] decodedBytes = BaseEncoding.base64().decode(rawBytes.toStringUtf8());\n        headerValue = HeaderValue.create(key, ByteString.copyFrom(decodedBytes));\n      } else {\n        headerValue = HeaderValue.create(key, rawBytes.toStringUtf8());\n      }\n      headersToModify.add(HeaderValueOption.create(\n          headerValue,\n          HeaderValueOption.HeaderAppendAction.valueOf(protoOption.getAppendAction().name())));\n    }\n\n    ImmutableList.Builder<String> headersToRemove = ImmutableList.builder();\n    for (String headerToRemove : mutation.getRemoveHeadersList()) {\n      HeaderValueValidationUtils.validateHeaderKey(headerToRemove);","sourceCodeStart":269,"sourceCodeEnd":305,"githubUrl":"https://github.com/grpc/grpc-java/blob/64daddc1f3d1975670f769f3e97bde8b2ba32d25/xds/src/main/java/io/grpc/xds/internal/extproc/ExternalProcessorUtil.java#L269-L305","documentation":"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.","triggerScenarios":"An ExternalProcessor's header mutation response (set/append/add headers) contains a value whose bytes exceed MAX_HEADER_LENGTH when applyHeaderMutations is called.","commonSituations":"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.","solutions":["Fix or reconfigure the ext_proc server so mutated header values stay under MAX_HEADER_LENGTH","Move large payloads out of headers into the request body or trailers metadata","Truncate or hash oversized values before returning them from the processor","Wrap applyHeaderMutations in try-catch to fail the RPC gracefully instead of propagating"],"exampleFix":"// ext_proc response before\nheaders.add(HeaderValue.newBuilder().setKey(\"x-trace\").setValue(largeJson).build())\n// after\nString digest = BaseEncoding.base64().encode(hash(largeJson.getBytes(UTF_8)));\nheaders.add(HeaderValue.newBuilder().setKey(\"x-trace-digest\").setValue(digest).build())","handlingStrategy":"try-catch","validationCode":"if (rawBytes.size() > HeaderValueValidationUtils.MAX_HEADER_LENGTH) { dropOrTruncate(header); }","typeGuard":"null","tryCatchPattern":"try { ExternalProcessorUtil.applyHeaderMutations(...); }\ncatch (IllegalArgumentException e) { log.warn(\"Oversized header value rejected\", e); failRpcWithStatus(ResourceExhausted); }","preventionTips":["Keep ext_proc header values small; move payloads to the body","Truncate or hash large values in the processor","Monitor ext_proc responses for size violations"],"tags":["xds","extproc","headers","limits"],"backgroundTag":"payload-too-large","analyzedSha":"64daddc1f3d1975670f769f3e97bde8b2ba32d25","analyzedAt":"2026-09-08T06:14:57.704Z","contentChangedAt":"2026-09-08T06:14:57.704Z","schemaVersion":2},"datasetVersion":"2026-09-14T05:17:10.506Z"}