TooTallNate/Java-WebSocket · error · InvalidFrameException

more than 125 octets

Error message

more than 125 octets

What it means

Draft_6455.translateSingleFramePayloadLength throws InvalidFrameException when a control frame (PING, PONG, or CLOSE) declares a payload longer than 125 octets. RFC 6455 forbids control frames from exceeding 125 bytes of payload, so the library rejects such frames during frame translation.

Solutions

1. Fix or reject the remote endpoint sending RFC-non-compliant control frames larger than 125 bytes
2. Catch InvalidFrameException in your WebSocketListener's onWebsocketError / process flow and close the connection with a protocol error (1002)
3. Verify no intermediate proxy is altering frames; test the peer with a standards-compliant client
4. Keep payloads for app-level pings within 125 bytes or use regular data frames instead

Example fix

// before: sending a huge custom ping payload
byte[] bigPayload = new byte[300];
webSocket.sendPing(bigPayload); // peer/lib rejects
// after
byte[] payload = new byte[100]; // <=125 bytes for control frames
webSocket.sendPing(payload);

// RFC 6455: control frame payloads must be <= 125 bytes
if (payload != null && payload.length > 125) {
  throw new IllegalArgumentException("Control frame payload must be <= 125 bytes");
}

try {
  webSocket.sendFrame(pingFrame);
} catch (WebsocketNotConnectedException | InvalidFrameException e) {
  log.warn("Control frame rejected: {}", e.getMessage());
  webSocket.close(CloseFrame.PROTOCOL_ERROR, "invalid control frame");
}

When it happens

Trigger: A PING, PONG, or CLOSE frame is received whose payload length field is >125 bytes; translateSingleFramePayloadLength detects optcode == PING/PONG/CLOSING and throws before length parsing continues.

Common situations: Interoperating with a non-conformant or malicious WebSocket peer that sends oversized control frames; buggy custom clients/servers; proxies or fuzzing tools that violate RFC 6455 control-frame limits.

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

• Unknown opcode
• Control frame can't have fin==false set
• closecode must not be sent over the wire
• 1007
• buffer size < 0

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

Appendix: source

Thrown at src/main/java/org/java_websocket/drafts/Draft_6455.java:619

   *
   * @param buffer            the buffer to read from
   * @param optcode           the decoded optcode
   * @param oldPayloadlength  the old payload length
   * @param maxpacketsize     the max packet size allowed
   * @param oldRealpacketsize the real packet size
   * @return the new payload data containing new payload length and new packet size
   * @throws InvalidFrameException  thrown if a control frame has an invalid length
   * @throws IncompleteException    if the maxpacketsize is smaller than the realpackagesize
   * @throws LimitExceededException if the payload length is to big
   */
  private TranslatedPayloadMetaData translateSingleFramePayloadLength(ByteBuffer buffer,
      Opcode optcode, int oldPayloadlength, int maxpacketsize, int oldRealpacketsize)
      throws InvalidFrameException, IncompleteException, LimitExceededException {
    int payloadlength = oldPayloadlength;
    int realpacketsize = oldRealpacketsize;
    if (optcode == Opcode.PING || optcode == Opcode.PONG || optcode == Opcode.CLOSING) {
      log.trace("Invalid frame: more than 125 octets");
      throw new InvalidFrameException("more than 125 octets");
    }
    if (payloadlength == 126) {
      realpacketsize += 2; // additional length bytes
      translateSingleFrameCheckPacketSize(maxpacketsize, realpacketsize);
      byte[] sizebytes = new byte[3];
      sizebytes[1] = buffer.get(/*1 + 1*/);
      sizebytes[2] = buffer.get(/*1 + 2*/);
      payloadlength = new BigInteger(sizebytes).intValue();
    } else {
      realpacketsize += 8; // additional length bytes
      translateSingleFrameCheckPacketSize(maxpacketsize, realpacketsize);
      byte[] bytes = new byte[8];
      for (int i = 0; i < 8; i++) {
        bytes[i] = buffer.get(/*1 + i*/);
      }
      long length = new BigInteger(bytes).longValue();
      translateSingleFrameCheckLengthLimit(length);
      payloadlength = (int) length;

View on GitHub (pinned to afeacbf8c0)