eclipse-vertx/vert.x · error · IllegalArgumentException

maxWebSockets must be > 0 or -1 (disabled)

Error message

maxWebSockets must be > 0 or -1 (disabled)

What it means

WebSocketClientOptions.setMaxConnections validates the maximum number of concurrent WebSocket connections. Only positive values or -1 (meaning disabled/unlimited) are accepted; 0 and any value below -1 are rejected with this IllegalArgumentException. (The message mentions maxWebSockets for backwards compatibility; the field is maxConnections.)

Source

Thrown at vertx-core/src/main/java/io/vertx/core/http/WebSocketClientOptions.java:308

  /**
   * Get the maximum of WebSockets per endpoint.
   *
   * @return  the max number of WebSockets
   */
  public int getMaxConnections() {
    return maxConnections;
  }

  /**
   * Set the max number of WebSockets per endpoint.
   *
   * @param maxConnections  the max value
   * @return a reference to this, so the API can be used fluently
   */
  public WebSocketClientOptions setMaxConnections(int maxConnections) {
    if (maxConnections == 0 || maxConnections < -1) {
      throw new IllegalArgumentException("maxWebSockets must be > 0 or -1 (disabled)");
    }
    this.maxConnections = maxConnections;
    return this;
  }

  /**
   * Set whether the client will offer the WebSocket per-frame deflate compression extension.
   *
   * @param offer {@code true} to offer the per-frame deflate compression extension
   * @return a reference to this, so the API can be used fluently
   */
  public WebSocketClientOptions setTryUsePerFrameCompression(boolean offer) {
    this.tryUsePerFrameCompression = offer;
    return this;
  }

  /**
   * @return {@code true} when the WebSocket per-frame deflate compression extension will be offered

View on GitHub (pinned to fb308bd8c3)

Solutions

1. Set a positive integer, e.g. setMaxConnections(50).
2. Use -1 explicitly to disable the connection limit.
3. Fix the JSON config value so maxWebSockets is > 0 or exactly -1 before calling fromJson.

Example fix

// before
WebSocketClientOptions opts = new WebSocketClientOptions().setMaxConnections(0);
// after
WebSocketClientOptions opts = new WebSocketClientOptions().setMaxConnections(-1); // unlimited

if (maxConnections != -1 && maxConnections <= 0) {
  throw new IllegalArgumentException("maxConnections must be > 0 or -1");
}
options.setMaxConnections(maxConnections);

When it happens

Trigger: Calling setMaxConnections(0) or setMaxConnections(-2) or lower, either directly or indirectly via WebSocketClientOptions.fromJson when a JSON config contains {"maxWebSockets": 0} (or a negative value other than -1).

Common situations: Loading client config from JSON files where someone wrote 0 thinking it meant 'no limit'; computing the limit from an expression that can evaluate to 0 (e.g. an empty pool size); migrating configs between Vert.x versions.

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

• workerPoolSize must be > 0
• blockedThreadCheckInterval must be > 0
• maxEventLoopExecuteTime must be > 0
• maxWorkerpExecuteTime must be > 0
• internalBlockingPoolSize must be > 0

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