{"record":{"id":"4b65ab810afeaed2","repo":"eclipse-vertx/vert.x","slug":"a-header-name-cannot-contain-some-prohibited-chara","errorCode":null,"errorMessage":"a header name cannot contain some prohibited characters, such as : ","messagePattern":"a header name cannot contain some prohibited characters, such as : ","errorType":"validation","errorClass":"IllegalArgumentException","httpStatus":null,"severity":"error","filePath":"vertx-core/src/main/java/io/vertx/core/http/impl/HttpUtils.java","lineNumber":843,"sourceCode":"    } 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    }\n  }\n\n  private static void validateSequenceHeaderName(CharSequence value) {","sourceCodeStart":825,"sourceCodeEnd":861,"githubUrl":"https://github.com/eclipse-vertx/vert.x/blob/fb308bd8c3f12c79f4ae89bef67fadf6c80d036e/vertx-core/src/main/java/io/vertx/core/http/impl/HttpUtils.java#L825-L861","documentation":"Beyond ASCII-ness, header names may only contain RFC 7230 token characters. Vert.x maintains a VALID_H_NAME_ASCII_CHARS table that forbids separators such as space, quotes, parentheses, comma, slash, colon, semicolon, angle brackets, equals, question mark, @, square brackets, backslash, braces, DEL and all control characters. This exception is thrown when any ASCII character of the header name is in that forbidden set.","triggerScenarios":"Setting a header name containing forbidden separators, e.g. \"Content Type\" (space), \"X-Foo:Bar\" (colon inside the name), \"X-User,Id\" (comma), \"my header\" — thrown from validateAsciiHeaderName/validateStringHeaderName/validateSequenceHeaderName via validateHeaderName on putHeader/put/remove operations.","commonSituations":"Accidentally including the colon when splitting raw \"Name: Value\" lines and passing the whole line as a name; using a display label with spaces as a header name; joining multiple header names with commas into one name.","solutions":["Remove the offending character from the name; split \"Name: Value\" on the first colon and trim before using the name part.","Use only token characters: letters, digits, and '-'/'_' style separators (e.g. \"Content-Type\", not \"Content Type\").","Pre-validate names with a regex like ^[!#$%&'*+.^_`|~0-9A-Za-z-]+$ before passing to Vert.x."],"exampleFix":"// before\nString line = \"Content-Type: application/json\";\nrequest.putHeader(line, \"application/json\"); // name contains ':' and space -> throws\n// after\nint idx = line.indexOf(':');\nrequest.putHeader(line.substring(0, idx).trim(), \"application/json\");","handlingStrategy":"validation","validationCode":"private static final java.util.regex.Pattern TOKEN = java.util.regex.Pattern.compile(\"^[!#$%&'*+.^_`|~0-9A-Za-z-]+$\");\npublic static boolean isValidHeaderName(String name) {\n  return TOKEN.matcher(name).matches();\n}","typeGuard":null,"tryCatchPattern":"try {\n  request.putHeader(name, value);\n} catch (IllegalArgumentException e) {\n  throw new BadRequestException(\"Illegal header name: \" + name);\n}","preventionTips":["Split raw 'Name: Value' header lines on the first ':' and trim the name part","Only use RFC 7230 token characters in header names; prefer letters/digits/hyphens","Validate header names from external configuration with a token-characters regex before use"],"tags":["http","headers","validation","token-characters"],"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"}