eclipse-vertx/vert.x · error · IllegalArgumentException

Scheme:

Error message

Scheme: 

What it means

WebSocketConnectOptions.setAbsoluteURI parses an absolute URI and requires the scheme to be exactly 'ws' or 'wss'. Any other scheme (http, https, ftp, or a missing one) throws this IllegalArgumentException. Vert.x WebSockets only connect over the ws/wss schemes.

Source

Thrown at vertx-core/src/main/java/io/vertx/core/http/WebSocketConnectOptions.java:310

    return this;
  }

  @Override
  public WebSocketConnectOptions setAbsoluteURI(URL url) {
    URI uri;
    try {
      uri = url.toURI();
    } catch (URISyntaxException e) {
      throw new IllegalArgumentException(e);
    }
    setAbsoluteURI(uri);
    return this;
  }

  private void setAbsoluteURI(URI uri) {
    String scheme = uri.getScheme();
    if (!"ws".equals(scheme) && !"wss".equals(scheme)) {
      throw new IllegalArgumentException("Scheme: " + scheme);
    }
    boolean ssl = scheme.length() == 3;
    int port = uri.getPort();
    if (port == -1) {
      port = ssl ? 443 : 80;
    };
    StringBuilder relativeUri = new StringBuilder();
    if (uri.getRawPath() != null) {
      relativeUri.append(uri.getRawPath());
    }
    if (uri.getRawQuery() != null) {
      relativeUri.append('?').append(uri.getRawQuery());
    }
    if (uri.getRawFragment() != null) {
      relativeUri.append('#').append(uri.getRawFragment());
    }
    setHost(uri.getHost());
    setPort(port);

View on GitHub (pinned to fb308bd8c3)

Solutions

1. Change the scheme to ws:// (or wss:// for TLS), e.g. setAbsoluteURI("wss://example.com/ws").
2. If you have an http(s) URL, replace the scheme programmatically before passing it.
3. Always include the scheme — a scheme-less URI also fails this check.

Example fix

// before
WebSocketConnectOptions opts = new WebSocketConnectOptions().setAbsoluteURI("https://example.com/events");
// after
WebSocketConnectOptions opts = new WebSocketConnectOptions().setAbsoluteURI("wss://example.com/events");

static String toWsScheme(String url) {
  return url.replaceFirst("^https?://", m -> url.startsWith("https") ? "wss://" : "ws://");
}
// ensure url starts with "ws://" or "wss://" before setAbsoluteURI

When it happens

Trigger: Calling new WebSocketConnectOptions().setAbsoluteURI("https://example.com/ws") or "example.com/socket" (no scheme); also triggered internally when a URI object passed to setAbsoluteURI(URI) has a non-ws scheme.

Common situations: Reusing an HTTP endpoint URL string for a WebSocket connection; forgetting the scheme entirely; building the URI from config where the scheme is http by default; typing ws:// wrong after copy-paste from a browser URL.

Understand the failure class

Background: "Invalid URL" errors: why new URL(), URI.parse, and reqwest::Url reject your string — missing scheme, whitespace, and bad path format — this error's family across 39 libraries.

Related errors

• Scheme:
• Invalid url:
• maxWebSockets must be > 0 or -1 (disabled)
• Protocol version ${version} not supported.
• Invalid connection header

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