{"record":{"id":"eb80af799f7963d1","repo":"eclipse-vertx/vert.x","slug":"invalid-websocket-version","errorCode":null,"errorMessage":"Invalid WebSocket version","messagePattern":"Invalid WebSocket version","errorType":"http","errorClass":"WebSocketHandshakeException","httpStatus":426,"severity":"error","filePath":"vertx-core/src/main/java/io/vertx/core/http/impl/http1/Http1ServerConnection.java","lineNumber":412,"sourceCode":"      subProtocols = String.join(\",\", webSocketConfig.getSubProtocols());\n    }\n    WebSocketDecoderConfig config = WebSocketDecoderConfig.newBuilder()\n      .allowExtensions(webSocketConfig.getUsePerMessageCompression() || webSocketConfig.getUsePerFrameCompression())\n      .maxFramePayloadLength(webSocketConfig.getMaxFrameSize())\n      .allowMaskMismatch(webSocketConfig.isUseUnmaskedFrames())\n      .closeOnProtocolViolation(false)\n      .build();\n    WebSocketServerHandshakerFactory factory = new WebSocketServerHandshakerFactory(wsURL, subProtocols, config);\n    WebSocketServerHandshaker shake = factory.newHandshaker(request.nettyRequest());\n    if (shake != null) {\n      return shake;\n    }\n    // See WebSocketServerHandshakerFactory.sendUnsupportedVersionResponse(ch);\n    request.response()\n      .putHeader(HttpHeaderNames.SEC_WEBSOCKET_VERSION, WebSocketVersion.V13.toHttpHeaderValue())\n      .setStatusCode(UPGRADE_REQUIRED.code())\n      .end();\n    throw new WebSocketHandshakeException(\"Invalid WebSocket version\");\n  }\n\n  public void netSocket(Handler<AsyncResult<NetSocket>> handler) {\n    Future<NetSocket> fut = netSocket();\n    if (handler != null) {\n      fut.onComplete(handler);\n    }\n  }\n\n  public Future<NetSocket> netSocket() {\n    Promise<NetSocket> promise = context.promise();\n    netSocket(promise);\n    return promise.future();\n  }\n\n  void netSocket(Promise<NetSocket> promise) {\n    context.execute(() -> {\n","sourceCodeStart":394,"sourceCodeEnd":430,"githubUrl":"https://github.com/eclipse-vertx/vert.x/blob/fb308bd8c3f12c79f4ae89bef67fadf6c80d036e/vertx-core/src/main/java/io/vertx/core/http/impl/http1/Http1ServerConnection.java#L394-L430","documentation":"This WebSocketHandshakeException is thrown in createHandshaker when the client requests an unsupported WebSocket sub-version in the Sec-WebSocket-Version header (only version 13 is supported). Vert.x responds with 426/Upgrade Required and includes a Sec-WebSocket-Version header advertising version 13.","triggerScenarios":"Client sends Sec-WebSocket-Version: 8 (Hixie-76/hybi-00 era clients), 7, or any value other than 13 during the WebSocket upgrade, and the server then calls the upgrade path (createHandshaker from createWebSocket).","commonSituations":"Very old browsers or legacy WebSocket client libraries (pre-RFC6455 draft versions); hand-rolled clients hardcoding an outdated version header; older corporate tooling behind the upgrade endpoint.","solutions":["Update the client to send Sec-WebSocket-Version: 13 (or omit it; modern libraries default to 13).","Upgrade the legacy WebSocket client library to an RFC 6455-compliant one.","Handle the 426 Upgrade Required response on the client and retry with version 13 as advertised in the response's Sec-WebSocket-Version header.","For genuinely legacy clients, place a translation layer/gateway that rewrites the handshake to version 13."],"exampleFix":"// before (client)\nrequest.putHeader(\"Sec-WebSocket-Version\", \"8\");\n\n// after\nrequest.putHeader(\"Sec-WebSocket-Version\", \"13\");","handlingStrategy":"validation","validationCode":"String ver = request.getHeader(HttpHeaders.SEC_WEBSOCKET_VERSION);\nif (ver == null || !\"13\".equals(ver.trim())) {\n  // send 426 with Sec-WebSocket-Version: 13\n}","typeGuard":null,"tryCatchPattern":"try {\n  serverRequest.toWebSocket();\n} catch (WebSocketHandshakeException e) {\n  respondUpgradeRequired();\n}","preventionTips":["Only use RFC 6455 (version 13) WebSocket clients","Upgrade legacy libraries that send Sec-WebSocket-Version: 8 or lower","Implement client handling of 426 Upgrade Required responses"],"tags":["websocket","http1","handshake","version-negotiation"],"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-14T00:17:10.932Z"}