eclipse-vertx/vert.x · error · IllegalArgumentException

keepAliveTimeout must be >= 0

Error message

keepAliveTimeout must be >= 0

What it means

Http1ClientConfig.setKeepAliveTimeout validates the duration and throws IllegalArgumentException when a non-null value is negative. A null duration is allowed (meaning use the default), but keepAliveTimeout cannot be less than zero seconds.

Source

Thrown at vertx-core/src/main/java/io/vertx/core/http/Http1ClientConfig.java:96

  }

  /**
   * @return the keep alive timeout value in seconds for HTTP/1.x connections
   */
  public Duration getKeepAliveTimeout() {
    return keepAliveTimeout;
  }

  /**
   * <p>Set the keep alive timeout for HTTP/1.1 connections. This value determines how long a connection remains
   * unused in the pool before being evicted and closed. A timeout of zero or {@code null} means there is no timeout.</p>
   *
   * @param keepAliveTimeout the timeout, in seconds
   * @return a reference to this, so the API can be used fluently
   */
  public Http1ClientConfig setKeepAliveTimeout(Duration keepAliveTimeout) {
    if (keepAliveTimeout != null && (keepAliveTimeout.isNegative())) {
      throw new IllegalArgumentException("keepAliveTimeout must be >= 0");
    }
    this.keepAliveTimeout = keepAliveTimeout;
    return this;
  }

  /**
   * Is pipe-lining enabled on the client
   *
   * @return {@code true} if pipe-lining is enabled
   */
  public boolean isPipelining() {
    return pipelining;
  }

  /**
   * Set whether pipe-lining is enabled on the client
   *
   * @param pipelining {@code true} if enabled

View on GitHub (pinned to fb308bd8c3)

Solutions

1. Pass a non-negative Duration (e.g. Duration.ofSeconds(30)) or null to use defaults
2. Clamp or validate configuration-provided values before constructing the Duration
3. If 'disabled' is intended, use null or an appropriately large positive duration, not a negative one

Example fix

// before
config.setKeepAliveTimeout(Duration.ofSeconds(-1));
// after
config.setKeepAliveTimeout(Duration.ofSeconds(30));

Duration t = /* from config */;
if (t != null && t.isNegative()) {
  throw new IllegalArgumentException("keepAliveTimeout must be >= 0, got: " + t);
}
clientConfig.setKeepAliveTimeout(t);

try {
  config.setKeepAliveTimeout(timeoutFromConfig);
} catch (IllegalArgumentException e) {
  logger.error("Invalid keepAliveTimeout: {}", timeoutFromConfig);
  config.setKeepAliveTimeout(Duration.ofSeconds(30)); // default
}

When it happens

Trigger: Passing a negative Duration such as Duration.ofSeconds(-1) to Http1ClientConfig.setKeepAliveTimeout, typically via computed values or misparsed configuration.

Common situations: Reading a timeout from config where a sentinel -1 means 'infinite' in another library, subtracting durations that produce a negative result, or unit confusion when building the Duration.

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.

• Timeouts: ETIMEDOUT, deadlines, and hung requests — what actually expires when a request times out.

Related errors

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

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