{"record":{"id":"8ac83abf50b8289b","repo":"eclipse-vertx/vert.x","slug":"a-header-name-cannot-contain-non-ascii-character","errorCode":null,"errorMessage":"a header name cannot contain non-ASCII character: <value>","messagePattern":"a header name cannot contain non-ASCII character: <value>","errorType":"validation","errorClass":"IllegalArgumentException","httpStatus":null,"severity":"error","filePath":"vertx-core/src/main/java/io/vertx/core/http/impl/HttpUtils.java","lineNumber":840,"sourceCode":"    if (value instanceof AsciiString) {\n      // no need to check for ASCII-ness anymore\n      validateAsciiHeaderName((AsciiString) value);\n    } else if(value instanceof String) {\n      validateStringHeaderName((String) value);\n    } else {\n      validateSequenceHeaderName(value);\n    }\n  }\n\n  private static void validateAsciiHeaderName(AsciiString value) {\n    final int len = value.length();\n    final int off = value.arrayOffset();\n    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    }","sourceCodeStart":822,"sourceCodeEnd":858,"githubUrl":"https://github.com/eclipse-vertx/vert.x/blob/fb308bd8c3f12c79f4ae89bef67fadf6c80d036e/vertx-core/src/main/java/io/vertx/core/http/impl/HttpUtils.java#L822-L858","documentation":"HTTP header names must be ASCII (RFC 7230 token characters). When a header name given as a Netty AsciiString contains a byte with the high bit set (byte < 0, i.e. a non-ASCII byte ≥ 0x80), Vert.x throws this IllegalArgumentException during validateHeaderName.","triggerScenarios":"Calling putHeader/removeHeader with an AsciiString name that contains bytes ≥ 0x80, e.g. a name built from UTF-8 encoded text like \"X-Naïve\" or localized header names.","commonSituations":"Constructing header names from user input or i18n labels; converting a UTF-8 String to AsciiString without checking its contents; older data pipelines that assumed Latin-1 header names.","solutions":["Use ASCII-only header names (letters, digits, and token characters like '-').","Move non-ASCII information (e.g. a language tag) into the header value or a standard parameter instead of the name.","If the name comes from external input, validate it matches [A-Za-z0-9-]+ before passing it to Vert.x."],"exampleFix":"// before\nheaders.set(AsciiString.cached(\"X-Utilisateur-Français\"), \"v\"); // non-ASCII -> throws\n// after\nheaders.set(AsciiString.cached(\"X-User-Locale\"), \"fr-FR\");","handlingStrategy":"validation","validationCode":"public static boolean isAsciiHeaderName(String name) {\n  for (int i = 0; i < name.length(); i++) {\n    if (name.charAt(i) > 0x7F) return false;\n  }\n  return true;\n}","typeGuard":null,"tryCatchPattern":"try {\n  request.putHeader(name, value);\n} catch (IllegalArgumentException e) {\n  throw new IllegalArgumentException(\"Header name must be ASCII: \" + name);\n}","preventionTips":["Use only [A-Za-z0-9-] characters in header names","Do not build header names from user input or localized labels","If wrapping names in Netty AsciiString, verify ASCII-ness first"],"tags":["http","headers","ascii","validation"],"backgroundTag":"invalid-identifier-format","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"}