apple/pkl · error · IllegalArgumentException

invalidHttpHeaderName

invalidHttpHeaderName

Error message

HTTP header `{0}` has invalid syntax.

What it means

This error means the HTTP header name failed Pkl's lexical syntax check (headerNameLike regex): valid header names are token characters per RFC 7230 (letters, digits, and select punctuation, no spaces or colons). Thrown from IoUtils.validateHeaderName after reserved checks pass.

Solutions

1. Fix the header name to a valid RFC 7230 token (no spaces/colons, ASCII token chars only).
2. Trim surrounding whitespace from the key.
3. Ensure the key is non-empty.

Example fix

// before
externalHttpHeaders {
  ["Content Type"] = "application/json"
}
// after
externalHttpHeaders {
  ["Content-Type"] = "application/json"
}

private static final Pattern TOKEN = Pattern.compile("[!#$%&'*+\\-.^_`|~0-9A-Za-z]+");
if (name == null || !TOKEN.matcher(name).matches()) throw new IllegalArgumentException("bad header name: " + name);

When it happens

Trigger: Header names containing spaces, colons, non-ASCII characters, or being empty, e.g. externalHttpHeaders["My Header"] = "value" or externalHttpHeaders[""] = "x".

Common situations: Typos in config files ("Content Type", "Accept-Language :"), programmatically built header maps with empty keys, or headers copied with surrounding whitespace from docs.

Understand the failure class

Background: "Invalid ... format", "must be in format X", "does not look like a ..." — invalid argument format errors across CLI tools and libraries — this error's family across 17 libraries.

Related errors

• invalidHttpHeaderValue
• invalidHttpHeaderReserved
• invalidHttpHeaderReservedPrefix
• invalidHttpHeaderValueTooLong
• Annotation `$fqn` is not a valid Java class. The name of…

AI-assisted analysis of apple/pkl@f3efcbfc9b (2026-09-08). Data as JSON: /api/errors/494e02c0beb06dd0. Report an issue: GitHub.

Appendix: source

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

      }
    }
    return false;
  }

  // keep in sync with stdlib EvaluatorSettings.HttpHeaderName
  public static void validateHeaderName(String headerName) {
    if (isReservedHeaderName(headerName)) {
      throw new IllegalArgumentException(
          ErrorMessages.create("invalidHttpHeaderReserved", headerName));
    }

    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) {

View on GitHub (pinned to f3efcbfc9b)