eclipse-vertx/vert.x · error · IllegalStateException

HTTP client must be configured for at least one HTTP version

Error message

HTTP client must be configured for at least one HTTP version

What it means

HttpClientBuilderInternal.build checks that the composed HttpClientOptions contains at least one protocol version. If setProtocolVersion/alpnVersions configuration results in an empty versions list, build throws this IllegalStateException — the client cannot negotiate any HTTP protocol.

Source

Thrown at vertx-core/src/main/java/io/vertx/core/http/impl/HttpClientBuilderInternal.java:297

  @Override
  public HttpClientInternal build() {

    HttpClientConfig co = clientConfig;
    if (co == null) {
      // We assume default client configuration
      co = new HttpClientConfig(new HttpClientOptions());
    }

    ClientSSLOptions ssl;
    if (sslOptions != null) {
      ssl = sslOptions.copy();
    } else {
      ssl = null;
    }

    if (co.getVersions().isEmpty()) {
      throw new IllegalStateException("HTTP client must be configured for at least one HTTP version");
    }

    HttpClientMetrics<?, ?> httpMetrics;
    if (vertx.metrics() != null) {
      httpMetrics = vertx.metrics() != null ? vertx.metrics().createHttpClientMetrics(co) : null;
    } else {
      httpMetrics = null;
    }

    HttpClientTransport quicTransport;
    if (co.getVersions().contains(HttpVersion.HTTP_3)) {
      quicTransport = new QuicHttpClientTransport(vertx, co);
    } else {
      quicTransport = null;
    }

    HttpClientTransport transport;
    String shared;

View on GitHub (pinned to fb308bd8c3)

Solutions

1. Ensure HttpClientOptions has at least one version, e.g. setProtocolVersion(HttpVersion.HTTP_2) or keep HTTP_1_1 default.
2. Fix the JSON config so alpnVersions/versions arrays are non-empty.
3. Validate the merged options with co.getVersions().isEmpty() before calling build().

Example fix

// before
HttpClientOptions opts = new HttpClientOptions().setAlpnVersions(List.of());
HttpClient client = vertx.httpClientBuilder().with(options(opts)).build();
// after
HttpClientOptions opts = new HttpClientOptions().setAlpnVersions(List.of(HttpVersion.HTTP_1_1, HttpVersion.HTTP_2));
HttpClient client = vertx.httpClientBuilder().with(options(opts)).build();

if (co.getVersions().isEmpty()) {
  co.setProtocolVersion(HttpVersion.HTTP_1_1);
}
HttpClient client = vertx.httpClientBuilder().with(options(co)).build();

When it happens

Trigger: Calling build() after configuring options whose version set is empty — e.g. via JSON config {"alpnVersions": []} combined with settings that drop default versions, or custom option composition that clears versions.

Common situations: Hand-edited JSON client configs; programmatically building options by removing versions for HTTP/1-only testing and removing all of them; merging config overlays that override arrays with empty arrays.

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

• workerPoolSize must be > 0
• blockedThreadCheckInterval must be > 0
• maxEventLoopExecuteTime must be > 0
• maxWorkerpExecuteTime must be > 0
• internalBlockingPoolSize must be > 0

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