eclipse-vertx/vert.x · error · IllegalArgumentException

a header name cannot contain non-ASCII character:

Error message

a header name cannot contain non-ASCII character: 

What it means

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.

Source

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

    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) {
    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);
      }
    }

View on GitHub (pinned to fb308bd8c3)

Solutions

1. Inspect the offending header name printed in the exception and remove/replace the non-ASCII character with a valid ASCII token character.
2. Sanitize header names at your boundary: strip or transliterate any char > 0x7F before passing it to putHeader/add.
3. 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.
4. Validate external/user-supplied header names before handing them to Vert.x (see validation guard).

Example fix

// before
request.putHeader("Clé-Cache", "no-cache"); // throws IllegalArgumentException
// after
request.putHeader("X-Cache-Key", "no-cache");

public static void checkAsciiHeaderName(String name) {
  for (int i = 0; i < name.length(); i++) {
    if (name.charAt(i) > 0x7F) {
      throw new IllegalArgumentException("Non-ASCII char in header name: " + name);
    }
  }
}
// call before request.putHeader(name, value);

public static boolean isAsciiHeaderName(CharSequence name) {
  for (int i = 0; i < name.length(); i++) {
    if (name.charAt(i) > 0x7F) return false;
  }
  return !name.isEmpty();
}

try {
  request.putHeader(name, value);
} catch (IllegalArgumentException e) {
  log.warn("Rejected invalid header name {}: {}", name, e.getMessage());
  // skip header or fail request construction gracefully
}

When it happens

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

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

Related errors

• a header value contains a prohibited character '127': <value
• a header value must not end with '\r' or '\n':<seq>
• a header value contains a prohibited character '127': <seq>
• only '\n' is allowed after '\r': <seq>
• only ' ' and '\t' are allowed after '\n': <seq>

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