{"record":{"id":"3301dec4ef58eec3","repo":"eclipse-vertx/vert.x","slug":"protocol-version-version-not-supported","errorCode":null,"errorMessage":"Protocol version ${version} not supported.","messagePattern":"Protocol version (.+?) not supported\\.","errorType":"exception","errorClass":"io.vertx.core.http.WebSocketHandshakeException","httpStatus":null,"severity":"error","filePath":"vertx-core/src/main/java/io/vertx/core/http/impl/http1/Http1ClientConnection.java","lineNumber":1233,"sourceCode":"          return request;\n        }\n      };\n    }\n    if (version == V00) {\n      return new WebSocketClientHandshaker00(\n        webSocketURL, V00, subprotocol, customHeaders, maxFramePayloadLength, -1) {\n        @Override\n        protected FullHttpRequest newHandshakeRequest() {\n          FullHttpRequest request = super.newHandshakeRequest();\n          if (!allowOriginHeader) {\n            request.headers().remove(ORIGIN);\n          }\n          return request;\n        }\n      };\n    }\n\n    throw new WebSocketHandshakeException(\"Protocol version \" + version + \" not supported.\");\n  }\n\n  ArrayList<WebSocketClientExtensionHandshaker> initializeWebSocketExtensionHandshakers(WebSocketClientOptions options) {\n    ArrayList<WebSocketClientExtensionHandshaker> extensionHandshakers = new ArrayList<>();\n    if (options.getTryUsePerFrameCompression()) {\n      extensionHandshakers.add(new DeflateFrameClientExtensionHandshaker(options.getCompressionLevel(),\n        false));\n    }\n\n    if (options.getTryUsePerMessageCompression()) {\n      extensionHandshakers.add(new PerMessageDeflateClientExtensionHandshaker(options.getCompressionLevel(),\n        ZlibCodecFactory.isSupportingWindowSizeAndMemLevel(), PerMessageDeflateServerExtensionHandshaker.MAX_WINDOW_SIZE,\n        options.getCompressionAllowClientNoContext(), options.getCompressionRequestServerNoContext()));\n    }\n\n    return extensionHandshakers;\n  }\n","sourceCodeStart":1215,"sourceCodeEnd":1251,"githubUrl":"https://github.com/eclipse-vertx/vert.x/blob/fb308bd8c3f12c79f4ae89bef67fadf6c80d036e/vertx-core/src/main/java/io/vertx/core/http/impl/http1/Http1ClientConnection.java#L1215-L1251","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","solutions":["Ensure the WebSocket version is RFC 6455: leave WebSocketConnectOptions.version at its default (13) or set it explicitly to 13","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","Verify any proxy/gateway in front is not rewriting the Sec-WebSocket-Version header; catch WebSocketHandshakeException and surface a clear config error"],"exampleFix":"// before\nWebSocketConnectOptions opts = new WebSocketConnectOptions().setURI(\"/ws\").setVersion(0);\nwebSocket.connect(opts); // Protocol version 0 not supported.\n// after\nWebSocketConnectOptions opts = new WebSocketConnectOptions().setURI(\"/ws\"); // default version 13 (RFC 6455)\nwebSocket.connect(opts);","handlingStrategy":"validation","validationCode":"WebSocketConnectOptions opts = new WebSocketConnectOptions();\nif (opts.getVersion() != 13 && opts.getVersion() != 8) {\n  throw new IllegalArgumentException(\"Unsupported WebSocket version: \" + opts.getVersion());\n}","typeGuard":"boolean isSupportedWsVersion(Integer v) {\n  return v == null || v == 13 || v == 8;\n}","tryCatchPattern":"webSocket.connect(opts)\n  .onFailure(t -> {\n    if (t instanceof WebSocketHandshakeException && t.getMessage().contains(\"not supported\")) {\n      // wrong WebSocket version in options or unsupported server\n    }\n  });","preventionTips":["Stick to the default WebSocket version 13 (RFC 6455)","Reject legacy hixie/draft endpoints at config-validation time","Verify proxies are not altering Sec-WebSocket-Version"],"tags":["websocket","handshake","protocol-version"],"backgroundTag":"unsupported-enum-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"}