eclipse-vertx/vert.x · error · IllegalArgumentException

a header value contains a prohibited character '127': <value

Error message

a header value contains a prohibited character '127': <value>

What it means

HTTP header values must be printable ASCII; Vert.x validates them before writing to the wire. A byte equal to 0x7F (DEL, decimal 127) anywhere in the value is prohibited and triggers this IllegalArgumentException. It is thrown from the fast-path validation scanning the full backing byte array (offset 0, full length).

Source

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

    } else if (value instanceof String) {
      validateStringHeaderValue((String) value);
    } else {
      validateSequenceHeaderValue(value);
    }
  }

  private static void validateAsciiHeaderValue(AsciiString value) {
    final int length = value.length();
    if (length == 0) {
      return;
    }
    byte[] asciiChars = value.array();
    int off = value.arrayOffset();
    if (off == 0 && length == asciiChars.length) {
      for (int index = 0; index < asciiChars.length; index++) {
        int latinChar = asciiChars[index] & 0xFF;
        if (latinChar == 0x7F) {
          throw new IllegalArgumentException("a header value contains a prohibited character '127': " + value);
        }
        // non-printable chars are rare so let's make it a fall-back method, whilst still accepting HTAB
        if (latinChar < 32 && latinChar != 0x09) {
          validateSequenceHeaderValue(value, index - off);
          break;
        }
      }
    } else {
      validateAsciiRangeHeaderValue(value, off, length, asciiChars);
    }
  }

  /**
   * This method is the slow-path generic version of {@link #validateAsciiHeaderValue(AsciiString)} which
   * is optimized for {@link AsciiString} instances which are backed by a 0-offset full-blown byte array.
   */
  private static void validateAsciiRangeHeaderValue(AsciiString value, int off, int length, byte[] asciiChars) {
    int end = off + length;

View on GitHub (pinned to fb308bd8c3)

Solutions

1. Sanitize the header value: strip or encode characters outside 0x20-0x7E (and HTAB)
2. Inspect the offending value bytes to find the source of the 0x7F byte
3. Base64-encode binary payloads before placing them in header values

Example fix

// before
String token = new String(rawBytes);
headers.add("X-Token", token); // rawBytes may contain 0x7F
// after
String token = Base64.getEncoder().encodeToString(rawBytes);
headers.add("X-Token", token);

static boolean isPrintableAscii(byte[] b) {
  for (byte x : b) { int c = x & 0xFF; if (c == 0x7F || (c < 0x20 && c != 0x09)) return false; }
  return true;
}
// call before headers.add/set

try {
  headers.add(name, value);
} catch (IllegalArgumentException e) {
  headers.add(name, sanitize(value));
}

When it happens

Trigger: Calling headers.add/set with an AsciiString/Buffer-backed value whose ASCII bytes include 0x7F, detected in the whole-array fast path (off == 0 && length == array length).

Common situations: Building header values from binary data or tokens that contain DEL; corrupt or truncated input; naive byte-array-to-String conversions carrying control characters.

Related errors

• a header name cannot contain non-ASCII character: <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/60f722da3a73e15e. Report an issue: GitHub.