TooTallNate/Java-WebSocket · error · InvalidDataException

1007

1007

Error message

Received text is no valid utf8 string!

What it means

CloseFrame.isValid validates outgoing close frames. A close frame with close code 1007 (NO_UTF8) must carry no reason string — by convention 1007 means 'I received invalid UTF-8' and any reason would itself need to be valid UTF-8/consistent. If code == NO_UTF8 and a reason text is present, InvalidDataException(1007) is thrown.

Solutions

1. Send close code 1007 with an empty reason string.
2. If you need to include an explanatory message, use a different close code (e.g. 1000 NORMAL or an app-range code 4000-4999) with the reason.
3. Validate close code/reason combinations before constructing the frame.

Example fix

// before
CloseFrame frame = new CloseFrame(CloseFrame.NO_UTF8, "bad utf8 from client");

// after
CloseFrame frame = new CloseFrame(CloseFrame.NO_UTF8, ""); // no reason with 1007

// guard before building a close frame
if (code == 1007 && reason != null && !reason.isEmpty()) {
    throw new IllegalArgumentException("close code 1007 must not carry a reason");
}

try {
    webSocket.close(1007, reason);
} catch (InvalidDataException | WebsocketNotConnectedException e) {
    logger.warn("invalid close frame parameters: {}", e.getMessage());
}

When it happens

Trigger: Constructing a CloseFrame (or calling WebSocket.close(1007, reason) / closeConnection paths) with close code 1007 and a non-empty reason string, then isValid() runs before the frame is sent.

Common situations: Applications trying to explain an invalid-UTF-8 condition by attaching a reason to code 1007; code paths that reuse a generic close(reason) helper with a fixed code map; tests that build CloseFrame payloads by hand.

Understand the failure class

Background: "Must be a positive integer", "Invalid value", "Unsupported": the invalid-argument-value error family, when a library rejects the value you pass — this error's family across 35 libraries.

Related errors

• 1002
• closecode must not be sent over the wire
• 1007
• address and connectionscontainer must not be null and you…
• buffer size < 0

AI-assisted analysis of TooTallNate/Java-WebSocket@afeacbf8c0 (2026-09-09). Data as JSON: /api/errors/0ba92d5df5f50382. Report an issue: GitHub.

Appendix: source

Thrown at src/main/java/org/java_websocket/framing/CloseFrame.java:229

  /**
   * Get the message that closeframe is containing
   *
   * @return the message in this frame
   */
  public String getMessage() {
    return reason;
  }

  @Override
  public String toString() {
    return super.toString() + "code: " + code;
  }

  @Override
  public void isValid() throws InvalidDataException {
    super.isValid();
    if (code == CloseFrame.NO_UTF8 && reason.isEmpty()) {
      throw new InvalidDataException(CloseFrame.NO_UTF8, "Received text is no valid utf8 string!");
    }
    if (code == CloseFrame.NOCODE && 0 < reason.length()) {
      throw new InvalidDataException(PROTOCOL_ERROR,
          "A close frame must have a closecode if it has a reason");
    }
    //Intentional check for code != CloseFrame.TLS_ERROR just to make sure even if the code earlier changes
    if ((code > CloseFrame.TLS_ERROR && code < 3000)) {
      throw new InvalidDataException(PROTOCOL_ERROR, "Trying to send an illegal close code!");
    }
    if (code == CloseFrame.ABNORMAL_CLOSE || code == CloseFrame.TLS_ERROR
        || code == CloseFrame.NOCODE || code > 4999 || code < 1000 || code == 1004) {
      throw new InvalidFrameException("closecode must not be sent over the wire: " + code);
    }
  }

  @Override
  public void setPayload(ByteBuffer payload) {
    code = CloseFrame.NOCODE;

View on GitHub (pinned to afeacbf8c0)