apple/pkl · error · IllegalArgumentException

invalidHttpHeaderReserved

invalidHttpHeaderReserved

Error message

HTTP header `{0}` is a reserved header.

What it means

Pkl throws this when an HTTP header name set via http.packages or similar HTTP settings is a reserved header name (a header the HTTP client manages itself, e.g. Authorization, Host, Content-Length). Pkl reserves these to prevent users from corrupting or spoofing the request the client assembles. The check lives in IoUtils.validateHeaderName and runs before any HTTP request is made.

Source

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

      }
    }
    return false;
  }

  private static boolean hasReservedHeaderPrefix(String headerName) {
    var normalizedHeader = headerName.toLowerCase(Locale.ROOT);
    for (var prefix : reservedHeaderPrefixes) {
      if (normalizedHeader.startsWith(prefix)) {
        return true;
      }
    }
    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));
    }

View on GitHub (pinned to f3efcbfc9b)

Solutions

1. Remove the reserved header from your configured header map and use the API's dedicated option instead (e.g. authentication settings instead of an Authorization header).
2. Check Pkl docs for the list of reserved header names and prefixes to see which name conflicts.
3. Rename the header if you actually meant a custom header (typos like 'authorization' vs reserved casing are caught separately by invalidHttpHeaderName).

Example fix

// before
externalHttpHeaders {
  ["Authorization"] = "Bearer xyz"
}
// after
authentication {
  basic { username = "user"; password = "xyz" }
}

private static final Set<String> RESERVED = Set.of("authorization","host","content-length","connection","upgrade","transfer-encoding");
if (RESERVED.contains(name.toLowerCase())) throw new IllegalArgumentException("reserved header: " + name);

When it happens

Trigger: Calling IoUtils.validateHeaderName (directly or via evaluator HTTP settings validation) with a header name that isReservedHeaderName() matches, e.g. setting externalHttpHeaders['Authorization'] or 'Host' in an EvaluatorSettings HttpHeaderName map.

Common situations: Users migrating curl-like configs that set Authorization or Content-Type manually into Pkl HTTP external headers; or intentionally trying to override proxy/auth headers that Pkl already controls.

Understand the failure class

Background: "Invalid value" and "allowed values are" config errors: what your library rejected and how to fix it — this error's family across 41 libraries.

Related errors

• invalidHttpHeaderReservedPrefix
• errorConnectingToHost
• ioErrorMakingHttpGet
• expectedNonEmptyCollection
• expectedSingleElementCollection

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