eclipse-vertx/vert.x · error · IllegalArgumentException

Unsupported HTTP version: <version>

Error message

Unsupported HTTP version: <version>

What it means

HttpUtils.toNettyHttpVersion maps Vert.x HttpVersion enums (HTTP_1_0, HTTP_1_1) to Netty's HttpVersion; any other value falls into the default branch and throws IllegalArgumentException. This is an internal invariant: only HTTP/1.0 and HTTP/1.1 are convertible in this HTTP/1 path.

Source

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

      }
    }
    if (buffer != null) {
      return buffer.toString();
    } else {
      return sequence;
    }
  }

  public static HttpVersion toNettyHttpVersion(io.vertx.core.http.HttpVersion version) {
    switch (version) {
      case HTTP_1_0: {
        return HttpVersion.HTTP_1_0;
      }
      case HTTP_1_1: {
        return HttpVersion.HTTP_1_1;
      }
      default:
        throw new IllegalArgumentException("Unsupported HTTP version: " + version);
    }
  }

  static io.vertx.core.http.HttpMethod toVertxMethod(String method) {
    return io.vertx.core.http.HttpMethod.valueOf(method);
  }

  private static final AsciiString TIMEOUT_EQ = AsciiString.of("timeout=");

  public static int parseKeepAliveHeaderTimeout(CharSequence value) {
    int len = value.length();
    int pos = 0;
    while (pos < len) {
      int idx = AsciiString.indexOf(value, ',', pos);
      int next;
      if (idx == -1) {
        idx = next = len;
      } else {

View on GitHub (pinned to fb308bd8c3)

Solutions

1. Ensure the HTTP version in options is HTTP_1_0 or HTTP_1_1 when using the HTTP/1 transport; use HTTP/2-specific APIs for HTTP_2
2. Check/normalize the version before invoking code that maps to Netty HTTP/1 versions
3. Upgrade Vert.x so HTTP_2 is routed through the correct transport path

Example fix

// before
HttpClient client = vertx.createHttpClient(new HttpClientOptions().setProtocolVersion(HttpVersion.HTTP_2).setKeepAlive(true)); // wrong transport
// after
HttpClientOptions opts = version == HttpVersion.HTTP_2
  ? new HttpClientOptions().setProtocolVersion(HttpVersion.HTTP_2).setHttp2ClearTextUpgrade(false)
  : new HttpClientOptions().setProtocolVersion(version);
HttpClient client = vertx.createHttpClient(opts);

if (version != HttpVersion.HTTP_1_0 && version != HttpVersion.HTTP_1_1) {
  throw new IllegalArgumentException("HTTP/1 transport requires HTTP_1_0 or HTTP_1_1, got " + version);
}

try {
  client.request(new RequestOptions().setHttpVersion(version));
} catch (IllegalArgumentException e) {
  // fall back to HTTP/1.1 or use HTTP/2 client APIs
}

When it happens

Trigger: Passing HttpVersion.HTTP_2 (or any other enum value) into a code path that calls toNettyHttpVersion, e.g. configuring an HTTP/1 client transport with HTTP_2, or custom pipeline code invoking the mapping with an unexpected version.

Common situations: Mixing HTTP/2 options with an HTTP/1-only client builder; version derived from untrusted input; version mismatches where new enum constants flow into old HTTP/1 mapping code.

Understand the failure class

Background: Invalid enum value errors: "Unknown type", "Invalid scope", "must be one of" — when a string is not on the library's allowed list — this error's family across 23 libraries.

Related errors

• Invalid setting
• code: <statusCode> (expected: 0+)
• size must be > 0
• maxExecuteTime must be > 0
• Unit must not be null

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