eclipse-vertx/vert.x · error · IllegalArgumentException

http3MaxPoolSize must be > 0

Error message

http3MaxPoolSize must be > 0

What it means

PoolOptions.setHttp3MaxSize() enforces that the HTTP/3 connection pool max size is at least 1. A value of 0 or negative throws this IllegalArgumentException since a zero-capacity pool cannot function.

Source

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

  /**
   * 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
   * @return a reference to this, so the API can be used fluently
   */
  public PoolOptions setHttp3MaxSize(int max) {
    if (max < 1) {
      throw new IllegalArgumentException("http3MaxPoolSize must be > 0");
    }
    this.http3MaxSize = max;
    return this;
  }

  /**
   * @return the pooled connection max lifetime unit
   */
  public TimeUnit getMaxLifetimeUnit() {
    return maxLifetimeUnit;
  }

  /**
   * Establish a max lifetime unit for pooled connections.
   *
   * @param maxLifetimeUnit pooled connection max lifetime unit
   * @return a reference to this, so the API can be used fluently
   */

View on GitHub (pinned to fb308bd8c3)

Solutions

1. Set http3MaxSize to a positive integer (>= 1).
2. If HTTP/3 is not used, omit the option instead of setting it to 0.
3. Clamp/validate configuration values before fromJson.

Example fix

// before
new PoolOptions().setHttp3MaxSize(0);
// after
new PoolOptions().setHttp3MaxSize(1); // or omit if HTTP/3 unused

int size = json.getInteger("http3MaxSize", 1);
if (size < 1) throw new IllegalArgumentException("http3MaxSize must be >= 1");
new PoolOptions().setHttp3MaxSize(size);

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

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

When it happens

Trigger: Calling setHttp3MaxSize(0) or negative, or PoolOptions.fromJson with an "http3MaxSize" entry <= 0 when configuring an HTTP/3 client.

Common situations: Template configs for HTTP/3 with placeholder 0 values; disabling HTTP/3 by zeroing its pool size instead of removing the option.

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
• http2MaxPoolSize 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/99ddf95b62ea48c5. Report an issue: GitHub.