{"record":{"id":"bb6afa76fa089b8e","repo":"eclipse-vertx/vert.x","slug":"websocket-upgrade-failure-statuscode","errorCode":null,"errorMessage":"WebSocket upgrade failure: ${statusCode}","messagePattern":"WebSocket upgrade failure: (.+?)","errorType":"http","errorClass":"UpgradeRejectedException","httpStatus":null,"severity":"error","filePath":"vertx-core/src/main/java/io/vertx/core/http/impl/websocket/WebSocketHandshakeInboundHandler.java","lineNumber":111,"sourceCode":"                upgrade.setSuccess(headers);\n              } else {\n                upgrade.setFailure(future.cause());\n              }\n            });\n          }\n        }\n      } finally {\n        content.release();\n      }\n    }\n  }\n\n  private HttpHeaders handshakeComplete(FullHttpResponse response) throws UpgradeRejectedException, WebSocketHandshakeException {\n    int sc = response.status().code();\n    if (sc != 101) {\n      String msg = \"WebSocket upgrade failure: \" + sc;\n      ByteBuf content = response.content();\n      throw new UpgradeRejectedException(\n        msg,\n        sc,\n        new HeadersAdaptor(response.headers()),\n        content != null ? BufferInternal.buffer(content) : null);\n    } else {\n      handshaker.finishHandshake(chctx.channel(), response);\n      return response.headers();\n    }\n  }\n}\n","sourceCodeStart":93,"sourceCodeEnd":122,"githubUrl":"https://github.com/eclipse-vertx/vert.x/blob/fb308bd8c3f12c79f4ae89bef67fadf6c80d036e/vertx-core/src/main/java/io/vertx/core/http/impl/websocket/WebSocketHandshakeInboundHandler.java#L93-L122","documentation":"Client-side handshake failure in WebSocketHandshakeInboundHandler.handshakeComplete: the server responded to the WebSocket upgrade request with a status code other than 101 Switching Protocols. The status code is included; the response body may carry the server's explanation, and the UpgradeRejectedException marks the connection as failed.","triggerScenarios":"Thrown at vertx-core/src/main/java/io/vertx/core/http/impl/websocket/WebSocketHandshakeInboundHandler.java:111 when the library encounters an invalid state.","commonSituations":"See trigger scenarios.","solutions":["Verify the endpoint URL and that the server supports WebSocket upgrade","Check credentials/auth if the status indicates rejection (e.g. 401/403)","Retry against a corrected endpoint or without conflicting headers"],"exampleFix":null,"handlingStrategy":"try-catch","validationCode":null,"typeGuard":null,"tryCatchPattern":null,"preventionTips":[],"tags":[],"backgroundTag":null,"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"}