grpc/grpc-java · error · IllegalArgumentException

Header value length exceeds maximum allowed length

Error message

Header value length exceeds maximum allowed length

What it means

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.

Source

Thrown at xds/src/main/java/io/grpc/xds/internal/grpcservice/HeaderValueValidationUtils.java:47

  /**
   * Validates that the header key is non-empty and within allowed length.
   * Throws {@link IllegalArgumentException} if invalid.
   */
  public static void validateHeaderKey(String key) {
    if (key == null || key.isEmpty() || key.length() > MAX_HEADER_LENGTH) {
      throw new IllegalArgumentException("Invalid header key: " + key);
    }
  }

  /**
   * Validates that the header value is within allowed length and contains valid ASCII characters.
   * Throws {@link IllegalArgumentException} if invalid.
   */
  public static void validateHeaderValue(String key, String value) {
    validateHeaderKey(key);
    if (value == null || value.length() > MAX_HEADER_LENGTH) {
      throw new IllegalArgumentException("Header value length exceeds maximum allowed length");
    }
    if (!key.endsWith("-bin") && !isValidAsciiHeaderValue(value)) {
      throw new IllegalArgumentException(
          "Invalid ASCII characters in header value for key: " + key);
    }
  }

  /**
   * Validates that the raw header value is within allowed length and contains valid ASCII
   * characters. Throws {@link IllegalArgumentException} if invalid.
   */
  public static void validateHeaderValue(String key, ByteString rawValue) {
    validateHeaderKey(key);
    if (rawValue == null || rawValue.size() > MAX_HEADER_LENGTH) {
      throw new IllegalArgumentException("Header value length exceeds maximum allowed length");
    }
    if (!key.endsWith("-bin") && !isValidAsciiHeaderValue(rawValue.toStringUtf8())) {
      throw new IllegalArgumentException(

View on GitHub (pinned to 64daddc1f3)

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

Example fix

// before
String token = loadLongToken(); // 500+ chars
HeaderValueValidationUtils.validateHeaderValue("x-auth", token);
// after
String token = loadLongToken();
if (token == null || token.length() > MAX_HEADER_LENGTH) {
  token = token.substring(0, MAX_HEADER_LENGTH); // or fail fast with a clear config error
}
HeaderValueValidationUtils.validateHeaderValue("x-auth", token);

Defensive patterns

Strategy: validation

Validate before calling

if (value == null || value.length() > MAX_HEADER_LENGTH) {
  throw new IllegalArgumentException("Header value for '" + key + "' too long");
}

Type guard

static boolean isValidHeaderValue(String v) {
  return v != null && v.length() <= MAX_HEADER_LENGTH;
}

Try / catch

try {
  HeaderValueValidationUtils.validateHeaderValue(key, value);
} catch (IllegalArgumentException e) {
  log.error("Header rejected: {}", e.getMessage());
}

Prevention

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

When it happens

Trigger: Calling HeaderValueValidationUtils.validateHeaderValue(String key, String value) with a null value or a value whose String length is greater than MAX_HEADER_LENGTH.

Common situations: 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.

Understand the failure class

Background: "value must be between 0 and 1" / "out of range" / "must not be negative" errors: fixing range-validation failures across open-source libraries — this error's family across 42 libraries.

Related errors

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