eclipse-vertx/vert.x · error · IllegalStateException

Unsupported WebSocket msg ${msg}

Error message

Unsupported WebSocket msg ${msg}

What it means

Protocol dispatch guard in WebSocketConnectionImpl.decodeFrame: the incoming Netty WebSocketFrame instance matched none of the known frame types (Binary, Close, Ping, Pong, Text, Continuation). The unmatched frame is appended to the message; this indicates an unexpected/extension frame type rather than user error.

Source

Thrown at vertx-core/src/main/java/io/vertx/core/http/impl/websocket/WebSocketConnectionImpl.java:235

  private WebSocketFrameInternal decodeFrame(io.netty.handler.codec.http.websocketx.WebSocketFrame msg) {
    ByteBuf payload = safeBuffer(msg.content());
    boolean isFinal = msg.isFinalFragment();
    WebSocketFrameType frameType;
    if (msg instanceof BinaryWebSocketFrame) {
      frameType = WebSocketFrameType.BINARY;
    } else if (msg instanceof CloseWebSocketFrame) {
      frameType = WebSocketFrameType.CLOSE;
    } else if (msg instanceof PingWebSocketFrame) {
      frameType = WebSocketFrameType.PING;
    } else if (msg instanceof PongWebSocketFrame) {
      frameType = WebSocketFrameType.PONG;
    } else if (msg instanceof TextWebSocketFrame) {
      frameType = WebSocketFrameType.TEXT;
    } else if (msg instanceof ContinuationWebSocketFrame) {
      frameType = WebSocketFrameType.CONTINUATION;
    } else {
      throw new IllegalStateException("Unsupported WebSocket msg " + msg);
    }
    return new WebSocketFrameImpl(frameType, payload, isFinal);
  }
}

View on GitHub (pinned to fb308bd8c3)

Solutions

1. Upgrade Vert.x/Netty so the frame type is supported
2. Inspect the reported frame class to identify the extension or malformed frame source

When it happens

Trigger: Thrown at vertx-core/src/main/java/io/vertx/core/http/impl/websocket/WebSocketConnectionImpl.java:235 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/06b3485a3ebcd001. Report an issue: GitHub.