What causes "The data size must not be greater than 125 bytes" in websockets/ws?

Keep ping payloads to small heartbeat tokens (e.g. a timestamp or counter) under 125 bytes.

websockets/ws · error · RangeError

The data size must not be greater than 125 bytes

Error message

The data size must not be greater than 125 bytes

What it means

Thrown by Sender.ping() when the ping payload exceeds 125 bytes. Ping is a WebSocket control frame and RFC 6455 section 5.5 mandates control-frame payloads MUST NOT exceed 125 bytes and MUST NOT be fragmented. The guard is at lib/sender.js:255-257 after computing byteLength from the string/blob/buffer input.

Source

Thrown at lib/sender.js:256

   */
  ping(data, mask, cb) {
    let byteLength;
    let readOnly;

    if (typeof data === 'string') {
      byteLength = Buffer.byteLength(data);
      readOnly = false;
    } else if (isBlob(data)) {
      byteLength = data.size;
      readOnly = false;
    } else {
      data = toBuffer(data);
      byteLength = data.length;
      readOnly = toBuffer.readOnly;
    }

    if (byteLength > 125) {
      throw new RangeError('The data size must not be greater than 125 bytes');
    }

    const options = {
      [kByteLength]: byteLength,
      fin: true,
      generateMask: this._generateMask,
      mask,
      maskBuffer: this._maskBuffer,
      opcode: 0x09,
      readOnly,
      rsv1: false
    };

    if (isBlob(data)) {
      if (this._state !== DEFAULT) {
        this.enqueue([this.getBlobData, data, false, options, cb]);
      } else {
        this.getBlobData(data, false, options, cb);

View on GitHub (pinned to ae1de54330)

Solutions

Keep ping payloads to small heartbeat tokens (e.g. a timestamp or counter) under 125 bytes.
Move large data to ws.send() instead of ws.ping().
If measuring liveness, send an empty ping (ws.ping()) and rely on the pong event, not the payload.

Example fix

// before
ws.ping(Buffer.alloc(200));

// after
ws.ping(Buffer.alloc(8)); // <= 125 bytes

Defensive patterns

Strategy: validation

Validate before calling

function pingSafe(ws, data, mask, cb) {
  const len =
    typeof data === 'string'
      ? Buffer.byteLength(data)
      : data && data.byteLength != null
        ? data.byteLength
        : 0;
  if (len > 125) {
    const err = new RangeError('ping payload > 125 bytes');
    if (cb) process.nextTick(cb, err);
    return;
  }
  ws.ping(data, mask, cb);
}

Type guard

function isSmallControlPayload(data) {
  if (data == null) return true;
  const len = typeof data === 'string' ? Buffer.byteLength(data) : data.byteLength;
  return len != null && len <= 125;
}

Try / catch

try {
  ws.ping(data, mask, cb);
} catch (err) {
  if (err instanceof RangeError && /must not be greater than 125 bytes/.test(err.message)) {
    // drop oversized ping or shrink payload
  } else {
    throw err;
  }
}

Prevention

Reserve ping payloads for tiny heartbeats (timestamp/counter).
Send large content via ws.send() data frames, not control frames.
Validate payload size before calling ping() to avoid a synchronous throw.

When it happens

Trigger: Calling ws.ping(data, mask, cb) on an OPEN connection where data (string, Blob, or ArrayBuffer/Buffer) has byte length > 125. The check runs after Sender.ping() normalizes the input to a byteLength and throws RangeError when byteLength > 125.

Common situations: Using ping as a heartbeat with large timestamps or serialized state; sending binary diagnostics in pings; copying example code that put large buffers in pings; misinterpreting ping as a general data channel.

Related errors

AI-assisted analysis of websockets/ws@ae1de54330 (2026-08-03). Data as JSON: /data/errors/a8313866d5a82416.json. Report an issue: GitHub.