eclipse-vertx/vert.x · error · IllegalArgumentException

connectTimeout must be >= 0 or -1 (use default client value)

Error message

connectTimeout must be >= 0 or -1 (use default client value)

What it means

Configuration validation in ConnectOptions.setTimeout: the per-connection override of the client connect timeout must be >= 0 or exactly -1 (sentinel meaning 'use the client's configured connect timeout'). Any other negative value is rejected.

Source

Thrown at vertx-core/src/main/java/io/vertx/core/net/ConnectOptions.java:222

  }

  /**
   * @return the value of connect timeout in millis or {@code -1} when using the client defined connect timeout {@link NetClientOptions#getConnectTimeout()}
   */
  public int getTimeout() {
    return timeout;
  }

  /**
   * Override the client connect timeout in millis when {@code timeout >= 0} or use the client defined connect timeout {@link NetClientOptions#getConnectTimeout()}
   * when {@code timeout == -1}.
   *
   * @param timeout connect timeout, in ms
   * @return a reference to this, so the API can be used fluently
   */
  public ConnectOptions setTimeout(int timeout) {
    if (timeout < -2) {
      throw new IllegalArgumentException("connectTimeout must be >= 0 or -1 (use default client value)");
    }
    this.timeout = timeout;
    return this;
  }
}

View on GitHub (pinned to fb308bd8c3)

Solutions

1. Pass -1 to defer to the client default, or a value >= 0
2. Validate user-supplied timeout overrides before applying

When it happens

Trigger: Thrown at vertx-core/src/main/java/io/vertx/core/net/ConnectOptions.java:222 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/073a37987e19a3f5. Report an issue: GitHub.