eclipse-vertx/vert.x · error · IllegalArgumentException

maxPoolSize must be > 0

Error message

maxPoolSize must be > 0

What it means

PoolOptions.setHttp1MaxSize() enforces that the HTTP/1.x connection pool max size is at least 1. Passing a value of 0 or negative throws this IllegalArgumentException because a pool that admits no connections is invalid.

Source

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

  /**
   * Get the maximum pool size for HTTP/1.x connections
   *
   * @return  the maximum pool size
   */
  public int getHttp1MaxSize() {
    return http1MaxSize;
  }

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

  /**
   * 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

View on GitHub (pinned to fb308bd8c3)

Solutions

1. Set http1MaxSize to a positive integer (>= 1); use the default (e.g. 5) if unsure.
2. Sanitize config-loaded values: coerce <= 0 to the default before calling fromJson/setHttp1MaxSize.
3. To limit connections, use a value like 1 rather than 0.

Example fix

// before
new PoolOptions().setHttp1MaxSize(0);
// after
new PoolOptions().setHttp1MaxSize(5); // any value >= 1

int size = parseSize(cfg.getString("http1MaxSize", "5"));
if (size < 1) throw new IllegalArgumentException("http1MaxSize must be >= 1");
new PoolOptions().setHttp1MaxSize(size);

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

try { poolOptions.setHttp1MaxSize(size); } catch (IllegalArgumentException e) { log.error("Bad http1MaxSize config", e); }

When it happens

Trigger: Calling setHttp1MaxSize(0) (or a negative value) directly, or via PoolOptions.fromJson with an "http1MaxSize" entry <= 0, e.g. loading client options from config JSON where maxPoolSize was set to 0.

Common situations: Externalized configuration where someone disabled pooling by setting the size to 0; computed pool sizes that floor to 0; copied Vert.x 3 options where 0 or negative sometimes meant 'unbounded'.

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

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