eclipse-vertx/vert.x · error · IllegalArgumentException

a header name cannot contain some prohibited characters, suc

Error message

a header name cannot contain some prohibited characters, such as :

What it means

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.

Source

Thrown at vertx-core/src/main/java/io/vertx/core/http/impl/HttpUtils.java:843

    } else if(value instanceof String) {
      validateStringHeaderName((String) value);
    } else {
      validateSequenceHeaderName(value);
    }
  }

  private static void validateAsciiHeaderName(AsciiString value) {
    final int len = value.length();
    final int off = value.arrayOffset();
    final byte[] asciiChars = value.array();
    for (int i = 0; i < len; i++) {
      // Check to see if the character is not an ASCII character, or invalid
      byte c = asciiChars[off + i];
      if (c < 0) {
        throw new IllegalArgumentException("a header name cannot contain non-ASCII character: " + value);
      }
      if (!VALID_H_NAME_ASCII_CHARS[c & 0x7F]) {
        throw new IllegalArgumentException("a header name cannot contain some prohibited characters, such as : " + value);
      }
    }
  }

  private static void validateStringHeaderName(String value) {
    for (int i = 0; i < value.length(); i++) {
      final char c = value.charAt(i);
      // Check to see if the character is not an ASCII character, or invalid
      if (c > 0x7f) {
        throw new IllegalArgumentException("a header name cannot contain non-ASCII character: " + value);
      }
      if (!VALID_H_NAME_ASCII_CHARS[c & 0x7F]) {
        throw new IllegalArgumentException("a header name cannot contain some prohibited characters, such as : " + value);
      }
    }
  }

  private static void validateSequenceHeaderName(CharSequence value) {

View on GitHub (pinned to fb308bd8c3)

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.

Example fix

// before
String line = "Content-Type: application/json";
request.putHeader(line, "application/json"); // name contains ':' and space -> throws
// after
int idx = line.indexOf(':');
request.putHeader(line.substring(0, idx).trim(), "application/json");

Defensive patterns

Strategy: validation

Validate before calling

private static final java.util.regex.Pattern TOKEN = java.util.regex.Pattern.compile("^[!#$%&'*+.^_`|~0-9A-Za-z-]+$");
public static boolean isValidHeaderName(String name) {
  return TOKEN.matcher(name).matches();
}

Try / catch

try {
  request.putHeader(name, value);
} catch (IllegalArgumentException e) {
  throw new BadRequestException("Illegal header name: " + name);
}

Prevention

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

When it happens

Trigger: 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.

Common situations: 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.

Understand the failure class

Background: "invalid id" errors: invalid identifier format — why libraries reject IDs before lookup, and how to fix them — this error's family across 37 libraries.

Related errors

AI-assisted analysis of eclipse-vertx/vert.x@fb308bd8c3 (2026-09-06). Data as JSON: /api/errors/4b65ab810afeaed2. Report an issue: GitHub.