eclipse-vertx/vert.x · error · UpgradeRejectedException

WebSocket upgrade failure: ${statusCode}

Error message

WebSocket upgrade failure: ${statusCode}

What it means

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.

Source

Thrown at vertx-core/src/main/java/io/vertx/core/http/impl/websocket/WebSocketHandshakeInboundHandler.java:111

                upgrade.setSuccess(headers);
              } else {
                upgrade.setFailure(future.cause());
              }
            });
          }
        }
      } finally {
        content.release();
      }
    }
  }

  private HttpHeaders handshakeComplete(FullHttpResponse response) throws UpgradeRejectedException, WebSocketHandshakeException {
    int sc = response.status().code();
    if (sc != 101) {
      String msg = "WebSocket upgrade failure: " + sc;
      ByteBuf content = response.content();
      throw new UpgradeRejectedException(
        msg,
        sc,
        new HeadersAdaptor(response.headers()),
        content != null ? BufferInternal.buffer(content) : null);
    } else {
      handshaker.finishHandshake(chctx.channel(), response);
      return response.headers();
    }
  }
}

View on GitHub (pinned to fb308bd8c3)

Solutions

1. Verify the endpoint URL and that the server supports WebSocket upgrade
2. Check credentials/auth if the status indicates rejection (e.g. 401/403)
3. Retry against a corrected endpoint or without conflicting headers

When it happens

Trigger: Thrown at vertx-core/src/main/java/io/vertx/core/http/impl/websocket/WebSocketHandshakeInboundHandler.java:111 when the library encounters an invalid state.

Common situations: See trigger scenarios.

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