eclipse-vertx/vert.x · error · IllegalStateException

WebSocket is closed

Error message

WebSocket is closed

What it means

Lifecycle guard in WebSocketImplBase.checkClosed: an operation (registering handlers, checking writeQueueFull, etc.) was attempted after the WebSocket was closed. The generic sentinel fires whenever isClosed() is true, preventing interaction with a dead socket.

Source

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

        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:
        // Echo back the content of the PING frame as PONG frame as specified in RFC 6455 Section 5.5.2
        conn.writeToChannel(new PongWebSocketFrame(frame.getBinaryData().copy()));
        break;
      case PONG:
        Handler<Buffer> pongHandler = pongHandler();
        if (pongHandler != null) {

View on GitHub (pinned to fb308bd8c3)

Solutions

1. Register handlers before the socket closes and stop using it afterwards
2. React to the closeHandler to halt pending operations
3. Route post-close errors through your failure handling instead of the throw path

When it happens

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