{"record":{"id":"a2224e0aec7bbfa9","repo":"grpc/grpc-java","slug":"header-value-length-exceeds-maximum-allowed-length-a2224e","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/grpcservice/HeaderValueValidationUtils.java","lineNumber":47,"sourceCode":"\n  /**\n   * Validates that the header key is non-empty and within allowed length.\n   * Throws {@link IllegalArgumentException} if invalid.\n   */\n  public static void validateHeaderKey(String key) {\n    if (key == null || key.isEmpty() || key.length() > MAX_HEADER_LENGTH) {\n      throw new IllegalArgumentException(\"Invalid header key: \" + key);\n    }\n  }\n\n  /**\n   * Validates that the header value is within allowed length and contains valid ASCII characters.\n   * Throws {@link IllegalArgumentException} if invalid.\n   */\n  public static void validateHeaderValue(String key, String value) {\n    validateHeaderKey(key);\n    if (value == null || value.length() > MAX_HEADER_LENGTH) {\n      throw new IllegalArgumentException(\"Header value length exceeds maximum allowed length\");\n    }\n    if (!key.endsWith(\"-bin\") && !isValidAsciiHeaderValue(value)) {\n      throw new IllegalArgumentException(\n          \"Invalid ASCII characters in header value for key: \" + key);\n    }\n  }\n\n  /**\n   * Validates that the raw header value is within allowed length and contains valid ASCII\n   * characters. Throws {@link IllegalArgumentException} if invalid.\n   */\n  public static void validateHeaderValue(String key, ByteString rawValue) {\n    validateHeaderKey(key);\n    if (rawValue == null || rawValue.size() > MAX_HEADER_LENGTH) {\n      throw new IllegalArgumentException(\"Header value length exceeds maximum allowed length\");\n    }\n    if (!key.endsWith(\"-bin\") && !isValidAsciiHeaderValue(rawValue.toStringUtf8())) {\n      throw new IllegalArgumentException(","sourceCodeStart":29,"sourceCodeEnd":65,"githubUrl":"https://github.com/grpc/grpc-java/blob/64daddc1f3d1975670f769f3e97bde8b2ba32d25/xds/src/main/java/io/grpc/xds/internal/grpcservice/HeaderValueValidationUtils.java#L29-L65","documentation":"gRPC-XDS validates custom header values before attaching them to xDS requests. This IllegalArgumentException is thrown when a header value is null or its length exceeds MAX_HEADER_LENGTH. It exists to prevent oversized headers from being sent to the control plane, matching header size limits enforced by Envoy-style proxies.","triggerScenarios":"Calling HeaderValueValidationUtils.validateHeaderValue(String key, String value) with a null value or a value whose String length is greater than MAX_HEADER_LENGTH.","commonSituations":"Configuring xDS metadata/custom headers from environment variables or config files that contain very long tokens, generated IDs, or concatenated values that accidentally exceed the length cap.","solutions":["Measure the value's length before passing it and truncate or shorten it to fit MAX_HEADER_LENGTH","Check for config mistakes where a whole file or multi-line secret is being used as a header value","If the value is legitimately large, send it out-of-band (e.g., a reference/URI) instead of as a header","Wrap the validateHeaderValue call in try-catch to handle the failure gracefully"],"exampleFix":"// before\nString token = loadLongToken(); // 500+ chars\nHeaderValueValidationUtils.validateHeaderValue(\"x-auth\", token);\n// after\nString token = loadLongToken();\nif (token == null || token.length() > MAX_HEADER_LENGTH) {\n  token = token.substring(0, MAX_HEADER_LENGTH); // or fail fast with a clear config error\n}\nHeaderValueValidationUtils.validateHeaderValue(\"x-auth\", token);","handlingStrategy":"validation","validationCode":"if (value == null || value.length() > MAX_HEADER_LENGTH) {\n  throw new IllegalArgumentException(\"Header value for '\" + key + \"' too long\");\n}","typeGuard":"static boolean isValidHeaderValue(String v) {\n  return v != null && v.length() <= MAX_HEADER_LENGTH;\n}","tryCatchPattern":"try {\n  HeaderValueValidationUtils.validateHeaderValue(key, value);\n} catch (IllegalArgumentException e) {\n  log.error(\"Header rejected: {}\", e.getMessage());\n}","preventionTips":["Check String length against MAX_HEADER_LENGTH before building headers","Never pass raw secrets/files as header values","Truncate long generated IDs","Validate header config at startup, not per-request"],"tags":["grpc","xds","header-validation","value-out-of-range"],"backgroundTag":"value-out-of-range","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"}