{"record":{"id":"3cdd43cc6203e53f","repo":"eclipse-vertx/vert.x","slug":"maxwebsockets-must-be-0-or-1-disabled","errorCode":null,"errorMessage":"maxWebSockets must be > 0 or -1 (disabled)","messagePattern":"maxWebSockets must be > 0 or -1 \\(disabled\\)","errorType":"validation","errorClass":"IllegalArgumentException","httpStatus":null,"severity":"error","filePath":"vertx-core/src/main/java/io/vertx/core/http/WebSocketClientOptions.java","lineNumber":308,"sourceCode":"\n  /**\n   * Get the maximum of WebSockets per endpoint.\n   *\n   * @return  the max number of WebSockets\n   */\n  public int getMaxConnections() {\n    return maxConnections;\n  }\n\n  /**\n   * Set the max number of WebSockets per endpoint.\n   *\n   * @param maxConnections  the max value\n   * @return a reference to this, so the API can be used fluently\n   */\n  public WebSocketClientOptions setMaxConnections(int maxConnections) {\n    if (maxConnections == 0 || maxConnections < -1) {\n      throw new IllegalArgumentException(\"maxWebSockets must be > 0 or -1 (disabled)\");\n    }\n    this.maxConnections = maxConnections;\n    return this;\n  }\n\n  /**\n   * Set whether the client will offer the WebSocket per-frame deflate compression extension.\n   *\n   * @param offer {@code true} to offer the per-frame deflate compression extension\n   * @return a reference to this, so the API can be used fluently\n   */\n  public WebSocketClientOptions setTryUsePerFrameCompression(boolean offer) {\n    this.tryUsePerFrameCompression = offer;\n    return this;\n  }\n\n  /**\n   * @return {@code true} when the WebSocket per-frame deflate compression extension will be offered","sourceCodeStart":290,"sourceCodeEnd":326,"githubUrl":"https://github.com/eclipse-vertx/vert.x/blob/fb308bd8c3f12c79f4ae89bef67fadf6c80d036e/vertx-core/src/main/java/io/vertx/core/http/WebSocketClientOptions.java#L290-L326","documentation":"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.)","triggerScenarios":"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).","commonSituations":"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.","solutions":["Set a positive integer, e.g. setMaxConnections(50).","Use -1 explicitly to disable the connection limit.","Fix the JSON config value so maxWebSockets is > 0 or exactly -1 before calling fromJson."],"exampleFix":"// before\nWebSocketClientOptions opts = new WebSocketClientOptions().setMaxConnections(0);\n// after\nWebSocketClientOptions opts = new WebSocketClientOptions().setMaxConnections(-1); // unlimited","handlingStrategy":"validation","validationCode":"if (maxConnections != -1 && maxConnections <= 0) {\n  throw new IllegalArgumentException(\"maxConnections must be > 0 or -1\");\n}\noptions.setMaxConnections(maxConnections);","typeGuard":null,"tryCatchPattern":null,"preventionTips":["Treat 0 as invalid, not 'unlimited'; use -1 for unlimited.","Validate JSON config values before WebSocketClientOptions.fromJson.","Clamp computed pool sizes to Math.max(1, n)."],"tags":["websocket","configuration","illegal-argument"],"backgroundTag":"invalid-config-value","analyzedSha":"fb308bd8c3f12c79f4ae89bef67fadf6c80d036e","analyzedAt":"2026-09-06T11:37:12.241Z","contentChangedAt":"2026-09-06T11:37:12.241Z","schemaVersion":2},"datasetVersion":"2026-09-14T05:17:10.506Z"}