eclipse-vertx/vert.x · error · IllegalArgumentException

maxLifetime must be >= 0

Error message

maxLifetime must be >= 0

What it means

PoolOptions.setMaxLifetime() enforces that the pool connection max lifetime is non-negative (a value in seconds; 0 or negative handling per contract requires >= 0). Passing a negative value throws this IllegalArgumentException.

Source

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

    return this;
  }

  /**
   * @return pooled connection max lifetime
   */
  public int getMaxLifetime() {
    return maxLifetime;
  }

  /**
   * Establish a max lifetime for pooled connections, a value of zero disables the maximum lifetime.
   *
   * @param maxLifetime the pool connection max lifetime
   * @return a reference to this, so the API can be used fluently
   */
  public PoolOptions setMaxLifetime(int maxLifetime) {
    if (maxLifetime < 0) {
      throw new IllegalArgumentException("maxLifetime must be >= 0");
    }
    this.maxLifetime = maxLifetime;
    return this;
  }

  /**
   * @return the connection pool cleaner period in ms.
   */
  public int getCleanerPeriod() {
    return cleanerPeriod;
  }

  /**
   * Set the connection pool cleaner period in milli seconds, a non positive value disables expiration checks and connections
   * will remain in the pool until they are closed.
   *
   * @param cleanerPeriod the pool cleaner period
   * @return a reference to this, so the API can be used fluently

View on GitHub (pinned to fb308bd8c3)

Solutions

1. Set maxLifetime to a non-negative integer; check the default in PoolOptions if you want the library default.
2. Replace -1 'infinite' sentinels with the documented default for unlimited lifetime.
3. Validate config JSON: reject or clamp negative maxLifetime before fromJson.

Example fix

// before
new PoolOptions().setMaxLifetime(-1); // meant 'infinite'
// after
new PoolOptions().setMaxLifetime(600); // or omit for the default

int lifetime = json.getInteger("maxLifetime", 0);
if (lifetime < 0) throw new IllegalArgumentException("maxLifetime must be >= 0");
new PoolOptions().setMaxLifetime(lifetime);

boolean validLifetime(Integer v) { return v != null && v >= 0; }

try { poolOptions.setMaxLifetime(lifetime); } catch (IllegalArgumentException e) { log.error("maxLifetime must be >= 0", e); }

When it happens

Trigger: Calling setMaxLifetime(-1) (a common 'infinite' sentinel from other libraries), or PoolOptions.fromJson with a negative "maxLifetime" entry.

Common situations: Porting config that used -1 to mean 'no expiration' from other pooling libraries (e.g. HikariCP's maxLifetime conventions); arithmetic on durations producing negative values.

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