eclipse-vertx/vert.x · error · IllegalArgumentException

HTTP keepAliveTimeout must be >= 0

Error message

HTTP keepAliveTimeout must be >= 0

What it means

Configuration validation in HttpClientConfig.setKeepAliveTimeout: the Duration controlling how long an idle HTTP connection remains in the pool before eviction must be non-negative (zero or null disables eviction), and it is propagated to all per-version configs. Negative durations are rejected.

Source

Thrown at vertx-core/src/main/java/io/vertx/core/http/HttpClientConfig.java:215

   */
  public HttpClientConfig setConnectTimeout(Duration connectTimeout) {
    tcpConfig.setConnectTimeout(connectTimeout);
    quicConfig.setConnectTimeout(connectTimeout);
    return this;
  }

  /**
   * <p>Set the keep alive timeout for HTTP 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>
   * <p>This configures each HTTP version with the same value, you can override this and configure each
   * version separately.</p>
   *
   * @param keepAliveTimeout the timeout, in seconds
   * @return a reference to this, so the API can be used fluently
   */
  public HttpClientConfig setKeepAliveTimeout(Duration keepAliveTimeout) {
    if (keepAliveTimeout != null && (keepAliveTimeout.isNegative())) {
      throw new IllegalArgumentException("HTTP keepAliveTimeout must be >= 0");
    }
    http1Config.setKeepAliveTimeout(keepAliveTimeout);
    http2Config.setKeepAliveTimeout(keepAliveTimeout);
    http3Config.setKeepAliveTimeout(keepAliveTimeout);
    return this;
  }

  /**
   * Set the idle timeout, zero or {@code null} means don't time out.
   * This determines if a connection will timeout and be closed if no data is received nor sent within the timeout.
   * <p>This configures both TCP and QUIC nested configurations, you can configure each of them separately
   * if you need to.</p>
   *
   * @param idleTimeout  the timeout
   * @return a reference to this, so the API can be used fluently
   */
  public HttpClientConfig setIdleTimeout(Duration idleTimeout) {
    tcpConfig.setIdleTimeout(idleTimeout);

View on GitHub (pinned to fb308bd8c3)

Solutions

1. Use a zero or positive Duration (or null)
2. Validate Duration configuration parsed from external sources

When it happens

Trigger: Thrown at vertx-core/src/main/java/io/vertx/core/http/HttpClientConfig.java:215 when the library encounters an invalid state.

Common situations: See trigger scenarios.

Understand the failure class

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

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