eclipse-vertx/vert.x · error · IllegalArgumentException

http2MaxPoolSize must be > 0

Error message

http2MaxPoolSize must be > 0

What it means

PoolOptions.setHttp2MaxSize() enforces that the HTTP/2 connection pool max size is at least 1. Values of 0 or less throw this IllegalArgumentException because the pool must be able to hold at least one connection.

Source

Thrown at vertx-core/src/main/java/io/vertx/core/http/PoolOptions.java:157

  /**
   * Get the maximum pool size for HTTP/2 connections
   *
   * @return  the maximum pool size
   */
  public int getHttp2MaxSize() {
    return http2MaxSize;
  }

  /**
   * Set the maximum pool size for HTTP/2 connections
   *
   * @param max  the maximum pool size
   * @return a reference to this, so the API can be used fluently
   */
  public PoolOptions setHttp2MaxSize(int max) {
    if (max < 1) {
      throw new IllegalArgumentException("http2MaxPoolSize must be > 0");
    }
    this.http2MaxSize = max;
    return this;
  }

  /**
   * Get the maximum pool size for HTTP/3 connections
   *
   * @return  the maximum pool size
   */
  public int getHttp3MaxSize() {
    return http3MaxSize;
  }

  /**
   * Set the maximum pool size for HTTP/3 connections
   *
   * @param max  the maximum pool size

View on GitHub (pinned to fb308bd8c3)

Solutions

1. Provide a positive integer for http2MaxSize (>= 1).
2. Validate/clamp JSON config values before PoolOptions.fromJson.
3. If multiplexing means you only need one connection, set the value to 1.

Example fix

// before
options.put("http2MaxSize", 0);
new PoolOptions().fromJson(options);
// after
options.put("http2MaxSize", 1); // >= 1
new PoolOptions().fromJson(options);

int size = json.getInteger("http2MaxSize", io.vertx.core.http.PoolOptions.DEFAULT_HTTP2_MAX_SIZE);
if (size < 1) size = io.vertx.core.http.PoolOptions.DEFAULT_HTTP2_MAX_SIZE;
new PoolOptions().setHttp2MaxSize(size);

boolean validPoolSize(Integer v) { return v != null && v >= 1; }

try { poolOptions.setHttp2MaxSize(size); } catch (IllegalArgumentException e) { log.error("http2MaxSize must be >= 1", e); }

When it happens

Trigger: Calling setHttp2MaxSize(0) or negative, or PoolOptions.fromJson with an "http2MaxSize" JSON entry <= 0, e.g. loading HttpClientOptions-derived pool config where the HTTP/2 pool size was set to 0.

Common situations: Config files tuned for HTTP/1.1 applied to HTTP/2 clients with a zeroed http2MaxSize; dynamic config generators emitting 0 as a 'disabled' sentinel.

Understand the failure class

Background: "Invalid value" and "allowed values are" config errors: what your library rejected and how to fix it — this error's family across 41 libraries.

Related errors

• maxPoolSize must be > 0
• http3MaxPoolSize must be > 0
• maxLifetime must be >= 0
• maxSize must be > 0
• keepAliveTimeout must be >= 0

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