eclipse-vertx/vert.x · error · IllegalStateException

Unsupported WebSocket msg ${frame}

Error message

Unsupported WebSocket msg ${frame}

What it means

Encoding dispatch guard in WebSocketImplBase.encodeFrame: the outgoing WebSocketFrameImpl's type matched none of the cases mapping Vert.x frames to Netty frames (BINARY, TEXT, CLOSE, CONTINUATION, PONG, PING). The frame is appended to the message; this signals an unknown/extension frame type rather than payload problems.

Source

Thrown at vertx-core/src/main/java/io/vertx/core/http/impl/websocket/WebSocketImplBase.java:335

  }

  private io.netty.handler.codec.http.websocketx.WebSocketFrame encodeFrame(WebSocketFrameImpl frame) {
    ByteBuf buf = safeBuffer(frame.getBinaryData());
    switch (frame.type()) {
      case BINARY:
        return new BinaryWebSocketFrame(frame.isFinal(), 0, buf);
      case TEXT:
        return new TextWebSocketFrame(frame.isFinal(), 0, buf);
      case CLOSE:
        return new CloseWebSocketFrame(true, 0, buf);
      case CONTINUATION:
        return new ContinuationWebSocketFrame(frame.isFinal(), 0, buf);
      case PONG:
        return new PongWebSocketFrame(buf);
      case PING:
        return new PingWebSocketFrame(buf);
      default:
        throw new IllegalStateException("Unsupported WebSocket msg " + frame);
    }
  }

  void checkClosed() {
    if (isClosed()) {
      throw new IllegalStateException("WebSocket is closed");
    }
  }

  public boolean isClosed() {
    synchronized (this) {
      return closed || closeStatusCode != null;
    }
  }

  void handleFrame(WebSocketFrameInternal frame) {
    switch (frame.type()) {
      case PING:

View on GitHub (pinned to fb308bd8c3)

Solutions

1. Send frames built with the standard WebSocketFrame factory methods
2. Upgrade Vert.x if a newer frame type should be supported

When it happens

Trigger: Thrown at vertx-core/src/main/java/io/vertx/core/http/impl/websocket/WebSocketImplBase.java:335 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/a58918d6f6cab740. Report an issue: GitHub.