eclipse-vertx/vert.x · error · IllegalArgumentException

reconnect attempts must be >= -1

Error message

reconnect attempts must be >= -1

What it means

NetClientOptions.setReconnectAttempts(int) rejects values below -1. The convention is: 0 means no reconnect attempts, -1 (or positive) controls the (un)limited retry count; anything < -1 is invalid and throws IllegalArgumentException immediately.

Source

Thrown at vertx-core/src/main/java/io/vertx/core/net/NetClientOptions.java:283

  public NetClientOptions setConnectTimeout(int connectTimeout) {
    super.setConnectTimeout(connectTimeout);
    return this;
  }

  @Override
  public NetClientOptions setMetricsName(String metricsName) {
    return (NetClientOptions) super.setMetricsName(metricsName);
  }

  /**
   * Set the value of reconnect attempts
   *
   * @param attempts  the maximum number of reconnect attempts
   * @return a reference to this, so the API can be used fluently
   */
  public NetClientOptions setReconnectAttempts(int attempts) {
    if (attempts < -1) {
      throw new IllegalArgumentException("reconnect attempts must be >= -1");
    }
    this.reconnectAttempts = attempts;
    return this;
  }

  /**
   * @return  the value of reconnect attempts
   */
  public int getReconnectAttempts() {
    return reconnectAttempts;
  }

  /**
   * Set the reconnect interval
   *
   * @param interval  the reconnect interval in ms
   * @return a reference to this, so the API can be used fluently
   */

View on GitHub (pinned to fb308bd8c3)

Solutions

1. Use exactly -1 for unlimited reconnect attempts (or whatever the docs define), never smaller
2. Clamp the value: Math.max(-1, attempts) before calling
3. Fix the JSON config so reconnectAttempts >= -1

Example fix

// before
options.setReconnectAttempts(-3);
// after
options.setReconnectAttempts(-1); // -1 = unlimited, 0 = never reconnect

int attempts = configuredAttempts;
if (attempts < -1) {
  throw new IllegalArgumentException("reconnectAttempts must be >= -1");
}
options.setReconnectAttempts(attempts);

boolean isValidReconnectAttempts(int n) { return n >= -1; }

When it happens

Trigger: Calling setReconnectAttempts(-2) or lower, or loading a JSON config via NetClientOptions.fromJson whose reconnectAttempts field is less than -1.

Common situations: Negative sentinel values from configuration files meant to mean 'infinite' (e.g. -999); copy-paste of -1 with an extra digit; arithmetic that decrements below -1 in retry loops building options.

Understand the failure class

Background: "value must be between 0 and 1" / "out of range" / "must not be negative" errors: fixing range-validation failures across open-source libraries — this error's family across 42 libraries.

Related errors

• reconnect interval must be >= 1
• keepAliveTimeout must be >= 0
• streamIdleTimeout must be >= 0
• streamReadIdleTimeout must be >= 0
• streamWriteIdleTimeout must be >= 0

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