eclipse-vertx/vert.x · error · IllegalStateException

This should be a close frame

Error message

This should be a close frame

What it means

API misuse guard in WebSocketFrameImpl.checkClose: closeStatusCode() or closeReason() was called on a WebSocket frame that is not a CLOSE frame. Only close frames carry a status code and reason, so parsing them from other frame types is rejected (the internal isClose() check failed).

Source

Thrown at vertx-core/src/main/java/io/vertx/core/http/impl/websocket/WebSocketFrameImpl.java:246

  private void parseCloseFrame() {
    int length = length();
    if (length < 2) {
      closeStatusCode = 1000;
      closeReason = null;
    } else {
      int index = binaryData.readerIndex();
      closeStatusCode = binaryData.getShort(index);
      if (length == 2) {
        closeReason = null;
      } else {
        closeReason = binaryData.toString(index + 2, length - 2, StandardCharsets.UTF_8);
      }
    }
  }

  private void checkClose() {
    if (!isClose())
      throw new IllegalStateException("This should be a close frame");
  }

  @Override
  public short closeStatusCode() {
    checkClose();
    if (!closeParsed)
      parseCloseFrame();
    return this.closeStatusCode;
  }

  @Override
  public String closeReason() {
    checkClose();
    if (!closeParsed)
      parseCloseFrame();
    return this.closeReason;
  }

View on GitHub (pinned to fb308bd8c3)

Solutions

1. Check frame.type() == WebSocketFrameType.CLOSE before reading closeStatusCode/closeReason
2. Handle binary/text frames separately from close frames

When it happens

Trigger: Thrown at vertx-core/src/main/java/io/vertx/core/http/impl/websocket/WebSocketFrameImpl.java:246 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/13db2126b6e95366. Report an issue: GitHub.