{"record":{"id":"62fde9d7e27c5d9a","repo":"apple/pkl","slug":"invalidhttpheaderreserved","errorCode":"invalidHttpHeaderReserved","errorMessage":"HTTP header `{0}` is a reserved header.","messagePattern":"HTTP header `(.+?)` is a reserved header\\.","errorType":"error_code","errorClass":"IllegalArgumentException","httpStatus":null,"severity":"error","filePath":"pkl-core/src/main/java/org/pkl/core/util/IoUtils.java","lineNumber":933,"sourceCode":"      }\n    }\n    return false;\n  }\n\n  private static boolean hasReservedHeaderPrefix(String headerName) {\n    var normalizedHeader = headerName.toLowerCase(Locale.ROOT);\n    for (var prefix : reservedHeaderPrefixes) {\n      if (normalizedHeader.startsWith(prefix)) {\n        return true;\n      }\n    }\n    return false;\n  }\n\n  // keep in sync with stdlib EvaluatorSettings.HttpHeaderName\n  public static void validateHeaderName(String headerName) {\n    if (isReservedHeaderName(headerName)) {\n      throw new IllegalArgumentException(\n          ErrorMessages.create(\"invalidHttpHeaderReserved\", headerName));\n    }\n\n    if (hasReservedHeaderPrefix(headerName)) {\n      throw new IllegalArgumentException(\n          ErrorMessages.create(\"invalidHttpHeaderReservedPrefix\", headerName));\n    }\n\n    if (!headerNameLike.matcher(headerName).matches()) {\n      throw new IllegalArgumentException(ErrorMessages.create(\"invalidHttpHeaderName\", headerName));\n    }\n  }\n\n  public static void validateHeaderValue(String headerValue) {\n    if (!headerValueLike.matcher(headerValue).matches()) {\n      throw new IllegalArgumentException(\n          ErrorMessages.create(\"invalidHttpHeaderValue\", headerValue));\n    }","sourceCodeStart":915,"sourceCodeEnd":951,"githubUrl":"https://github.com/apple/pkl/blob/f3efcbfc9b60d30053b0536d664948d7aa1b8673/pkl-core/src/main/java/org/pkl/core/util/IoUtils.java#L915-L951","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","solutions":["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).","Check Pkl docs for the list of reserved header names and prefixes to see which name conflicts.","Rename the header if you actually meant a custom header (typos like 'authorization' vs reserved casing are caught separately by invalidHttpHeaderName)."],"exampleFix":"// before\nexternalHttpHeaders {\n  [\"Authorization\"] = \"Bearer xyz\"\n}\n// after\nauthentication {\n  basic { username = \"user\"; password = \"xyz\" }\n}","handlingStrategy":"validation","validationCode":"private static final Set<String> RESERVED = Set.of(\"authorization\",\"host\",\"content-length\",\"connection\",\"upgrade\",\"transfer-encoding\");\nif (RESERVED.contains(name.toLowerCase())) throw new IllegalArgumentException(\"reserved header: \" + name);","typeGuard":null,"tryCatchPattern":null,"preventionTips":["Keep the reserved-name list in sync with IoUtils (it mirrors stdlib EvaluatorSettings.HttpHeaderName).","Use the client's dedicated auth/proxy settings instead of hand-set reserved headers.","Validate header maps at config load time, before any request is issued."],"tags":["http","validation","pkl"],"backgroundTag":"invalid-config-value","analyzedSha":"f3efcbfc9b60d30053b0536d664948d7aa1b8673","analyzedAt":"2026-09-08T13:10:45.570Z","contentChangedAt":"2026-09-08T13:10:45.570Z","schemaVersion":2},"datasetVersion":"2026-09-14T11:17:12.474Z"}