apple/pkl · error · IllegalArgumentException

invalidHttpHeaderValueTooLong

invalidHttpHeaderValueTooLong

Error message

HTTP Header value is invalid because it is longer than 4096 characters. Value: `{0}`

What it means

Validation in IoUtils (validateHeaderValue region): an HTTP header value exceeding 4096 characters is rejected with IllegalArgumentException before it can reach the HTTP client. The input at fault is an oversized header value, typically supplied via evaluator HTTP headers or resource reader options.

Solutions

Shorten the header value below 4096 characters.
Move bulk data out of headers into the request body or a different transport.

Example fix

// before
["X-Data"] = veryLargeBlob // 5000+ chars
// after
["X-Data-Ref"] = "s3://bucket/data.json"

Defensive patterns

Strategy: validation

Validate before calling

if (value != null && value.length() > 4096) throw new IllegalArgumentException("header value too long: " + value.length());

Prevention

Keep large payloads in bodies or files, not headers.
Deduplicate/normalize long tokens (JWTs, certs) before use.
Check length limits of intermediaries (proxies often cap at 4-8KB per header block).

When it happens

Trigger: Configuring an external HTTP header whose value length exceeds 4096, e.g. embedding a huge JWT, certificate, or blob in a header via EvaluatorSettings externalHttpHeaders.

Common situations: Very long JWT/OAuth tokens, inline-encoded certificates, or accidentally concatenating multiple values into one header.

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 apple/pkl@f3efcbfc9b (2026-09-08). Data as JSON: /api/errors/18cf759cb59d7f8e. Report an issue: GitHub.

Appendix: source

Thrown at pkl-core/src/main/java/org/pkl/core/util/IoUtils.java:953

    }

    if (hasReservedHeaderPrefix(headerName)) {
      throw new IllegalArgumentException(
          ErrorMessages.create("invalidHttpHeaderReservedPrefix", headerName));
    }

    if (!headerNameLike.matcher(headerName).matches()) {
      throw new IllegalArgumentException(ErrorMessages.create("invalidHttpHeaderName", headerName));
    }
  }

  public static void validateHeaderValue(String headerValue) {
    if (!headerValueLike.matcher(headerValue).matches()) {
      throw new IllegalArgumentException(
          ErrorMessages.create("invalidHttpHeaderValue", headerValue));
    }
    if (headerValue.length() > 4096) {
      throw new IllegalArgumentException(
          ErrorMessages.create("invalidHttpHeaderValueTooLong", headerValue));
    }
  }

  private static @Nullable String getFilenameExtension(String fileName) {
    var dotIndex = fileName.lastIndexOf('.');
    // 0 if hidden file (e.g. `.gitignore`); not an extension
    if (dotIndex == -1 || dotIndex == 0) {
      return null;
    }
    return fileName.substring(dotIndex + 1);
  }

  public static @Nullable Path findExecutableOnPath(String executable) {
    var pathEnvVar = System.getenv("PATH");
    if (pathEnvVar == null) {
      return null;
    }

View on GitHub (pinned to f3efcbfc9b)