{"record":{"id":"629e054f001ffded","repo":"eclipse-vertx/vert.x","slug":"invalid-websocket-location","errorCode":null,"errorMessage":"Invalid WebSocket location","messagePattern":"Invalid WebSocket location","errorType":"http","errorClass":"WebSocketHandshakeException","httpStatus":400,"severity":"error","filePath":"vertx-core/src/main/java/io/vertx/core/http/impl/http1/Http1ServerConnection.java","lineNumber":390,"sourceCode":"      request.response()\n        .setStatusCode(BAD_REQUEST.code())\n        .end(\"\\\"Connection\\\" header must be \\\"Upgrade\\\".\");\n      throw new WebSocketHandshakeException(\"Invalid connection header\");\n    }\n    if (request.method() != io.vertx.core.http.HttpMethod.GET) {\n      request.response()\n        .setStatusCode(METHOD_NOT_ALLOWED.code())\n        .end();\n      throw new WebSocketHandshakeException(\"Invalid HTTP method\");\n    }\n    String wsURL;\n    try {\n      wsURL = HttpUtils.getWebSocketLocation(request, isSsl());\n    } catch (Exception e) {\n      request.response()\n        .setStatusCode(BAD_REQUEST.code())\n        .end(\"Invalid request URI\");\n      throw new WebSocketHandshakeException(\"Invalid WebSocket location\", e);\n    }\n    String subProtocols = null;\n    if (webSocketConfig.getSubProtocols() != null) {\n      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()","sourceCodeStart":372,"sourceCodeEnd":408,"githubUrl":"https://github.com/eclipse-vertx/vert.x/blob/fb308bd8c3f12c79f4ae89bef67fadf6c80d036e/vertx-core/src/main/java/io/vertx/core/http/impl/http1/Http1ServerConnection.java#L372-L408","documentation":"This WebSocketHandshakeException is thrown in createHandshaker when HttpUtils.getWebSocketLocation(request, isSsl()) throws while computing the WebSocket location (the ws/wss URL derived from the request Host and URI). Vert.x responds 400 with \"Invalid request URI\" and aborts the handshake.","triggerScenarios":"A WebSocket upgrade request with a malformed or missing Host header, or an unusable request URI such that the WebSocket location URL cannot be constructed (any exception from getWebSocketLocation).","commonSituations":"Requests through proxies that drop or rewrite the Host header; HTTP/1.0 requests without Host; clients sending absolute-form or malformed request URIs; unusual Host headers that break URI building (e.g. invalid port).","solutions":["Ensure the client sends a valid Host header with the correct host and port (HTTP/1.1 requires Host).","Configure the proxy/load balancer to preserve the Host header.","Check the request URI for malformed characters and fix the client URL.","Catch WebSocketHandshakeException in your upgrade handler and return a descriptive 400 so clients can diagnose the bad request."],"exampleFix":"// before (client through proxy losing Host)\nhttpClient.request(HttpMethod.GET, \"http://backend/ws\");\n\n// after\nhttpClient.request(HttpMethod.GET, \"http://backend/ws\")\n  .compose(req -> req.putHeader(\"Host\", \"backend:8080\").send());","handlingStrategy":"validation","validationCode":"String host = request.getHeader(HttpHeaders.HOST);\nif (host == null || host.isEmpty()) {\n  // cannot derive WebSocket location; reject early\n}","typeGuard":null,"tryCatchPattern":"try {\n  serverRequest.toWebSocket();\n} catch (WebSocketHandshakeException e) {\n  respondBadRequest(\"Invalid request URI\");\n}","preventionTips":["Require HTTP/1.1 (with Host header) for WebSocket upgrades","Configure proxies to preserve the Host header","Validate client URLs for malformed URIs before connecting"],"tags":["websocket","http1","handshake","uri","host-header"],"backgroundTag":"invalid-url-format","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"}