TooTallNate/Java-WebSocket · error · IllegalArgumentException

unknown scheme:

Error message

unknown scheme: 

What it means

getPort() resolves the connection port from the URI scheme, accepting only "ws" (default 80) and "wss" (default 443). Any other scheme — including accidental values like null (URI without scheme), "http", or typos — reaches the else branch and throws. Fires during connect setup, before the handshake.

Solutions

1. Use a URI whose scheme is exactly "ws" or "wss", e.g. `new URI("wss://host:443/path")`.
2. Normalize http/https URIs to ws/wss before constructing the WebSocketClient.
3. Check uri.getScheme() beforehand and fail fast with a clear error for unsupported schemes.

When it happens

Trigger: Thrown at src/main/java/org/java_websocket/client/WebSocketClient.java:626 when the library encounters an invalid state.

Common situations: See trigger scenarios.

AI-assisted analysis of TooTallNate/Java-WebSocket@afeacbf8c0 (2026-09-09). Data as JSON: /api/errors/57071ad8ce34b245. Report an issue: GitHub.

Appendix: source

Thrown at src/main/java/org/java_websocket/client/WebSocketClient.java:626

    // If you run into problem on Android (NoSuchMethodException), check out the wiki https://github.com/TooTallNate/Java-WebSocket/wiki/No-such-method-error-setEndpointIdentificationAlgorithm
    // Perform hostname validation
    sslParameters.setEndpointIdentificationAlgorithm("HTTPS");
  }

  /**
   * Extract the specified port
   *
   * @return the specified port or the default port for the specific scheme
   */
  private int getPort() {
    int port = uri.getPort();
    String scheme = uri.getScheme();
    if ("wss".equals(scheme)) {
      return port == -1 ? WebSocketImpl.DEFAULT_WSS_PORT : port;
    } else if ("ws".equals(scheme)) {
      return port == -1 ? WebSocketImpl.DEFAULT_PORT : port;
    } else {
      throw new IllegalArgumentException("unknown scheme: " + scheme);
    }
  }

  /**
   * Create and send the handshake to the other endpoint
   *
   * @throws InvalidHandshakeException a invalid handshake was created
   */
  private void sendHandshake() throws InvalidHandshakeException {
    String path;
    String part1 = uri.getRawPath();
    String part2 = uri.getRawQuery();
    if (part1 == null || part1.length() == 0) {
      path = "/";
    } else {
      path = part1;
    }
    if (part2 != null) {

View on GitHub (pinned to afeacbf8c0)