eclipse-vertx/vert.x · error · io.vertx.core.http.WebSocketHandshakeException

Protocol version ${version} not supported.

Error message

Protocol version ${version} not supported.

What it means

Http1ClientConnection.createWebSocket (WebSocketHandshakeException) throws this when the WebSocket subprotocol version requested/served is not among the supported WebSocket handshake versions (Vert.x supports the RFC 6455 version 13 handshake, with legacy handling for version 8 in some paths). An unknown version string/version header means the client cannot build the handshake request, so it fails explicitly.

Source

Thrown at vertx-core/src/main/java/io/vertx/core/http/impl/http1/Http1ClientConnection.java:1233

          return request;
        }
      };
    }
    if (version == V00) {
      return new WebSocketClientHandshaker00(
        webSocketURL, V00, subprotocol, customHeaders, maxFramePayloadLength, -1) {
        @Override
        protected FullHttpRequest newHandshakeRequest() {
          FullHttpRequest request = super.newHandshakeRequest();
          if (!allowOriginHeader) {
            request.headers().remove(ORIGIN);
          }
          return request;
        }
      };
    }

    throw new WebSocketHandshakeException("Protocol version " + version + " not supported.");
  }

  ArrayList<WebSocketClientExtensionHandshaker> initializeWebSocketExtensionHandshakers(WebSocketClientOptions options) {
    ArrayList<WebSocketClientExtensionHandshaker> extensionHandshakers = new ArrayList<>();
    if (options.getTryUsePerFrameCompression()) {
      extensionHandshakers.add(new DeflateFrameClientExtensionHandshaker(options.getCompressionLevel(),
        false));
    }

    if (options.getTryUsePerMessageCompression()) {
      extensionHandshakers.add(new PerMessageDeflateClientExtensionHandshaker(options.getCompressionLevel(),
        ZlibCodecFactory.isSupportingWindowSizeAndMemLevel(), PerMessageDeflateServerExtensionHandshaker.MAX_WINDOW_SIZE,
        options.getCompressionAllowClientNoContext(), options.getCompressionRequestServerNoContext()));
    }

    return extensionHandshakers;
  }

View on GitHub (pinned to fb308bd8c3)

Solutions

1. Ensure the WebSocket version is RFC 6455: leave WebSocketConnectOptions.version at its default (13) or set it explicitly to 13
2. If the remote server only supports legacy drafts (version 0/8 variants), upgrade or replace that endpoint — Vert.x does not support pre-RFC6455 handshakes
3. Verify any proxy/gateway in front is not rewriting the Sec-WebSocket-Version header; catch WebSocketHandshakeException and surface a clear config error

Example fix

// before
WebSocketConnectOptions opts = new WebSocketConnectOptions().setURI("/ws").setVersion(0);
webSocket.connect(opts); // Protocol version 0 not supported.
// after
WebSocketConnectOptions opts = new WebSocketConnectOptions().setURI("/ws"); // default version 13 (RFC 6455)
webSocket.connect(opts);

WebSocketConnectOptions opts = new WebSocketConnectOptions();
if (opts.getVersion() != 13 && opts.getVersion() != 8) {
  throw new IllegalArgumentException("Unsupported WebSocket version: " + opts.getVersion());
}

boolean isSupportedWsVersion(Integer v) {
  return v == null || v == 13 || v == 8;
}

webSocket.connect(opts)
  .onFailure(t -> {
    if (t instanceof WebSocketHandshakeException && t.getMessage().contains("not supported")) {
      // wrong WebSocket version in options or unsupported server
    }
  });

When it happens

Trigger: Creating a WebSocket with a WebSocketConnectOptions/WebSocketClientOptions whose (or the server's advertised) version is not 13/8 (e.g. version 0/hixie-75 or a bogus custom version), so the handshake builder switch falls through to the throw.

Common situations: Connecting to an extremely old or non-standard WebSocket endpoint that only speaks pre-RFC6455 drafts; passing a hand-edited Sec-WebSocket-Version value; copy-pasted options from another framework expecting draft-17/hixie support.

Related errors

• Invalid connection header
• Invalid HTTP method
• Invalid WebSocket location
• Invalid WebSocket version
• Promise already completed

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