eclipse-vertx/vert.x · error · IllegalArgumentException

You must set at least one supported HTTP version

Error message

You must set at least one supported HTTP version

What it means

HttpServerBuilderImpl.build() throws this IllegalArgumentException when the builder's version configuration contains none of the supported HTTP versions (HTTP/1.0, HTTP/1.1, HTTP/2 or HTTP/3), so no transport (TCP or QUIC) can be selected for the server.

Source

Thrown at vertx-core/src/main/java/io/vertx/core/http/impl/HttpServerBuilderImpl.java:94

    boolean useQuic = config.getVersions().contains(HttpVersion.HTTP_3);
    if (useQuic && sslOptions == null) {
      throw new NullPointerException("SSL configuration is necessary for a QUIC server");
    }
    HttpServer server;
    if (useTcp) {
      if (useQuic) {
        HybridHttpServer compositeServer = new HybridHttpServer(vertx, new HttpServerConfig(config), sslOptions.copy(), sslEngineOptions);
        server = new CleanableHttpServer(vertx, compositeServer);
      } else {
        if (sslOptions != null) {
          sslOptions = sslOptions.copy();
        }
        server = new CleanableHttpServer(vertx, new TcpHttpServer(vertx, new HttpServerConfig(config), sslOptions, sslEngineOptions, null, registerWebSocketWriteHandlers));
      }
    } else if (useQuic) {
      server = new CleanableHttpServer(vertx, new QuicHttpServer(vertx, new HttpServerConfig(config), sslOptions.copy(), null));
    } else {
      throw new IllegalArgumentException("You must set at least one supported HTTP version");
    }
    Handler<HttpConnection> handler = connectHandler;
    if (handler != null) {
      return server.connectionHandler(handler);
    }
    return server;
  }
}

View on GitHub (pinned to fb308bd8c3)

Solutions

1. Call addVersion(HttpVersion.HTTP_1_1, port) (or the desired version) on the builder before build()
2. Fix the configuration source so at least one HTTP version flag is true
3. Add a build-time validation that at least one version is configured before constructing the server

Example fix

// before
HttpServer server = vertx.createHttpServer_builder()
  .setPort(8080)
  .build(); // no version set -> throws
// after
HttpServer server = vertx.createHttpServer_builder()
  .addVersion(HttpVersion.HTTP_1_1, 8080)
  .build();

if (versions.isEmpty() || versions.stream().noneMatch(v -> v == HttpVersion.HTTP_1_0 || v == HttpVersion.HTTP_1_1 || v == HttpVersion.HTTP_2 || v == HttpVersion.HTTP_3)) {
  throw new IllegalArgumentException("configure at least one HTTP version via addVersion");
}

try {
  server = builder.build();
} catch (IllegalArgumentException e) {
  if (e.getMessage().contains("at least one supported HTTP version")) {
    builder.addVersion(HttpVersion.HTTP_1_1, port);
    server = builder.build();
  } else { throw e; }
}

When it happens

Trigger: Building an HttpServer without ever calling addVersion(...), or after configuring only an unsupported/empty version set on the HttpServerConfig.

Common situations: Programmatic config assembled from flags/env where all version flags are false; forgetting to call addVersion because older Vert.x APIs defaulted to HTTP/1.1 automatically.

Understand the failure class

Background: "X is required", "must be set", "cannot be empty": the missing-required-config error family, from Vertex AI project/location to WeChat keys — this error's family across 18 libraries.

Related errors

• SSL configuration is necessary for a QUIC server
• keepAliveTimeout must be >= 0
• Cannot have pipelining with no keep alive
• streamIdleTimeout must be >= 0
• streamReadIdleTimeout must be >= 0

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