{"record":{"id":"02f216c140d7ac1a","repo":"eclipse-vertx/vert.x","slug":"a-header-name-cannot-contain-non-ascii-character-02f216","errorCode":null,"errorMessage":"a header name cannot contain non-ASCII character: ","messagePattern":"a header name cannot contain non-ASCII character: ","errorType":"validation","errorClass":"IllegalArgumentException","httpStatus":null,"severity":"error","filePath":"vertx-core/src/main/java/io/vertx/core/http/impl/HttpUtils.java","lineNumber":853,"sourceCode":"    final byte[] asciiChars = value.array();\n    for (int i = 0; i < len; i++) {\n      // Check to see if the character is not an ASCII character, or invalid\n      byte c = asciiChars[off + i];\n      if (c < 0) {\n        throw new IllegalArgumentException(\"a header name cannot contain non-ASCII character: \" + value);\n      }\n      if (!VALID_H_NAME_ASCII_CHARS[c & 0x7F]) {\n        throw new IllegalArgumentException(\"a header name cannot contain some prohibited characters, such as : \" + value);\n      }\n    }\n  }\n\n  private static void validateStringHeaderName(String value) {\n    for (int i = 0; i < value.length(); i++) {\n      final char c = value.charAt(i);\n      // Check to see if the character is not an ASCII character, or invalid\n      if (c > 0x7f) {\n        throw new IllegalArgumentException(\"a header name cannot contain non-ASCII character: \" + value);\n      }\n      if (!VALID_H_NAME_ASCII_CHARS[c & 0x7F]) {\n        throw new IllegalArgumentException(\"a header name cannot contain some prohibited characters, such as : \" + value);\n      }\n    }\n  }\n\n  private static void validateSequenceHeaderName(CharSequence value) {\n    for (int i = 0; i < value.length(); i++) {\n      final char c = value.charAt(i);\n      // Check to see if the character is not an ASCII character, or invalid\n      if (c > 0x7f) {\n        throw new IllegalArgumentException(\"a header name cannot contain non-ASCII character: \" + value);\n      }\n      if (!VALID_H_NAME_ASCII_CHARS[c & 0x7F]) {\n        throw new IllegalArgumentException(\"a header name cannot contain some prohibited characters, such as : \" + value);\n      }\n    }","sourceCodeStart":835,"sourceCodeEnd":871,"githubUrl":"https://github.com/eclipse-vertx/vert.x/blob/fb308bd8c3f12c79f4ae89bef67fadf6c80d036e/vertx-core/src/main/java/io/vertx/core/http/impl/HttpUtils.java#L835-L871","documentation":"Vert.x validates HTTP header names before sending or receiving them, because the HTTP protocol only allows a restricted set of printable ASCII characters in a header name (RFC 7230 token characters). This IllegalArgumentException is thrown by HttpUtils.validateStringHeaderName(String) when a header name contains a character with code point above 0x7F, i.e. any non-ASCII character (accents, CJK, emoji, curly quotes, etc.). It fails fast instead of producing a malformed HTTP request that a server would reject or misinterpret.","triggerScenarios":"Calling any Vert.x HTTP API that accepts a header name as a java.lang.String and passing a name containing a character > 0x7F — e.g. httpClient.request().putHeader(\"X-Utilisateur-Français\", \"v\"), headers().add(\"Contenido-报告\", ...), or copying headers from an external map whose keys are non-ASCII.","commonSituations":"Copying headers from an upstream proxy or legacy system that uses localized header names; typos where a non-breaking space (U+00A0) or smart quote sneaks into a header name constant; generating header names from user input or i18n resources; porting code from systems that tolerated 8-bit header names.","solutions":["Inspect the offending header name printed in the exception and remove/replace the non-ASCII character with a valid ASCII token character.","Sanitize header names at your boundary: strip or transliterate any char > 0x7F before passing it to putHeader/add.","If the header is meant to carry localized data, move that data into the header VALUE (UTF-8 encoded) and keep the name a plain ASCII token.","Validate external/user-supplied header names before handing them to Vert.x (see validation guard)."],"exampleFix":"// before\nrequest.putHeader(\"Clé-Cache\", \"no-cache\"); // throws IllegalArgumentException\n// after\nrequest.putHeader(\"X-Cache-Key\", \"no-cache\");","handlingStrategy":"validation","validationCode":"public static void checkAsciiHeaderName(String name) {\n  for (int i = 0; i < name.length(); i++) {\n    if (name.charAt(i) > 0x7F) {\n      throw new IllegalArgumentException(\"Non-ASCII char in header name: \" + name);\n    }\n  }\n}\n// call before request.putHeader(name, value);","typeGuard":"public static boolean isAsciiHeaderName(CharSequence name) {\n  for (int i = 0; i < name.length(); i++) {\n    if (name.charAt(i) > 0x7F) return false;\n  }\n  return !name.isEmpty();\n}","tryCatchPattern":"try {\n  request.putHeader(name, value);\n} catch (IllegalArgumentException e) {\n  log.warn(\"Rejected invalid header name {}: {}\", name, e.getMessage());\n  // skip header or fail request construction gracefully\n}","preventionTips":["Define header names as ASCII string constants, never built from user/i18n input.","Sanitize externally supplied header names against ^[!#$%&'*+.^_`|~0-9A-Za-z-]+$ before use.","Put non-ASCII payload data in header values (UTF-8), not names.","Beware of copy-paste introducing non-breaking spaces into header name literals."],"tags":["http","headers","validation","vertx-core"],"backgroundTag":"invalid-header-name","analyzedSha":"fb308bd8c3f12c79f4ae89bef67fadf6c80d036e","analyzedAt":"2026-09-06T11:37:12.241Z","contentChangedAt":"2026-09-06T11:37:12.241Z","schemaVersion":2},"datasetVersion":"2026-09-14T00:17:10.932Z"}