{"record":{"id":"b5519cc4d418a657","repo":"eclipse-vertx/vert.x","slug":"scheme-b5519c","errorCode":null,"errorMessage":"Scheme: ","messagePattern":"Scheme: ","errorType":"validation","errorClass":"IllegalArgumentException","httpStatus":null,"severity":"error","filePath":"vertx-core/src/main/java/io/vertx/core/http/impl/WebSocketClientImpl.java","lineNumber":149,"sourceCode":"\n  public Future<WebSocket> webSocket(int port, String host, String requestURI) {\n    return webSocket(new WebSocketConnectOptions().setURI(requestURI).setHost(host).setPort(port));\n  }\n\n  public Future<WebSocket> webSocket(WebSocketConnectOptions options) {\n    return webSocket(vertx.getOrCreateContext(), options);\n  }\n\n  static WebSocketConnectOptions webSocketConnectOptionsAbs(String url, MultiMap headers, WebSocketVersion version, List<String> subProtocols) {\n    URI uri;\n    try {\n      uri = new URI(url);\n    } catch (URISyntaxException e) {\n      throw new IllegalArgumentException(e);\n    }\n    String scheme = uri.getScheme();\n    if (!\"ws\".equals(scheme) && !\"wss\".equals(scheme)) {\n      throw new IllegalArgumentException(\"Scheme: \" + scheme);\n    }\n    boolean ssl = scheme.length() == 3;\n    int port = uri.getPort();\n    if (port == -1) port = ssl ? 443 : 80;\n    StringBuilder relativeUri = new StringBuilder();\n    if (uri.getRawPath() != null) {\n      relativeUri.append(uri.getRawPath());\n    }\n    if (uri.getRawQuery() != null) {\n      relativeUri.append('?').append(uri.getRawQuery());\n    }\n    if (uri.getRawFragment() != null) {\n      relativeUri.append('#').append(uri.getRawFragment());\n    }\n    return new WebSocketConnectOptions()\n      .setHost(uri.getHost())\n      .setPort(port).setSsl(ssl)\n      .setURI(relativeUri.toString())","sourceCodeStart":131,"sourceCodeEnd":167,"githubUrl":"https://github.com/eclipse-vertx/vert.x/blob/fb308bd8c3f12c79f4ae89bef67fadf6c80d036e/vertx-core/src/main/java/io/vertx/core/http/impl/WebSocketClientImpl.java#L131-L167","documentation":"WebSocketClientImpl.webSocketConnectOptionsAbs parses a WebSocket URL passed to the client and requires its scheme to be exactly ws or wss. If the URI's scheme is anything else (http, https, missing scheme, or a typo), it throws IllegalArgumentException(\"Scheme: \" + scheme) so the connect request never proceeds with a non-WebSocket endpoint.","triggerScenarios":"Calling webSocket()/webSocketAbs with a URL like \"http://host/sock\", \"//host/path\", \"host:9999/path\" (no scheme, so uri.getScheme() is the hostname or null), or \"WS://host\" (case-sensitive comparison fails only if server-side, but here scheme is lowercased by URI parsing, so mostly wrong scheme or missing scheme).","commonSituations":"Config value taken from an environment variable or property meant for an HTTP URL reused for WebSockets; users forgetting to swap http->ws or https->wss; URLs built by string concatenation that omit the scheme; trailing/leading whitespace producing a null or mangled scheme.","solutions":["Change the URL to use the ws:// or wss:// scheme (wss for TLS, which also selects port 443/SSL)","If you only have an http(s) URL, derive the scheme: http->ws, https->wss","Trim whitespace and validate the URL before passing it to webSocket()","Prefer passing WebSocketConnectOptions with explicit host/port/ssl/uri instead of a raw URL string"],"exampleFix":"// before\nclient.webSocket(\"https://example.com/events\", ws -> {...});\n// after\nclient.webSocket(\"wss://example.com/events\", ws -> {...});","handlingStrategy":"validation","validationCode":"static boolean isValidWsUrl(String url) {\n  try {\n    java.net.URI u = new java.net.URI(url);\n    return \"ws\".equals(u.getScheme()) || \"wss\".equals(u.getScheme());\n  } catch (URISyntaxException e) { return false; }\n}","typeGuard":null,"tryCatchPattern":"try {\n  client.webSocket(url, ws -> {...});\n} catch (IllegalArgumentException e) {\n  if (e.getMessage() != null && e.getMessage().startsWith(\"Scheme:\")) {\n    throw new IllegalArgumentException(\"URL must use ws:// or wss://: \" + url, e);\n  }\n  throw e;\n}","preventionTips":["Store WebSocket endpoints with explicit ws:// or wss:// schemes in configuration","Convert http(s) endpoints to ws(s) programmatically instead of hand-editing URLs","Trim and validate all endpoint URLs loaded from env vars/properties","Prefer WebSocketConnectOptions with explicit setSsl/setHost/setPort/setURI over raw URL strings"],"tags":["websocket","url","client"],"backgroundTag":"invalid-url-format","analyzedSha":"fb308bd8c3f12c79f4ae89bef67fadf6c80d036e","analyzedAt":"2026-09-06T11:37:12.241Z","contentChangedAt":"2026-09-06T11:37:12.241Z","schemaVersion":2},"datasetVersion":"2026-09-14T00:17:10.932Z"}