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() at sender.js:255-257 when the ping payload (computed from the string byte-length, Blob size, or buffer length) exceeds 125 bytes. Per RFC 6455 §5.5, ping is a control frame and control frames cannot carry more than 125 bytes of application data. The limit is enforced before any framing or masking happens.

Solutions

1. Keep ping payloads small: use a short monotonic counter or timestamp (e.g. Buffer.allocUnsafe(8) or a short string), staying under 125 bytes.
2. If you need to send larger keepalive data, use ws.send(data, { binary: true }) instead of ws.ping().
3. Truncate or omit the data: ws.ping() with no argument sends an empty ping, which is sufficient for most liveness checks.

Example fix

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

// after
ws.ping(); // empty ping is enough for liveness
// or, if you need a nonce:
ws.ping(crypto.randomBytes(8));

function pingSize(data) {
  if (data == null) return 0;
  if (typeof data === 'string') return Buffer.byteLength(data);
  if (typeof data === 'object' && typeof data.size === 'number') return data.size; // Blob
  return data.length;
}
// usage: if (pingSize(data) <= 125) ws.ping(data);

function isPingSafe(data) {
  const len = data == null ? 0
    : typeof data === 'string' ? Buffer.byteLength(data)
    : typeof data.size === 'number' ? data.size
    : data.length;
  return len <= 125;
}

try {
  ws.ping(data);
} catch (err) {
  if (err instanceof RangeError && /125 bytes/.test(err.message)) {
    // payload too large; send empty ping or a data message instead
    ws.ping();
  } else throw err;
}

When it happens

Trigger: Calling ws.ping(data, mask, cb) or the internal sender.ping() with a string longer than 125 UTF-8 bytes, a Blob larger than 125 bytes, or a Buffer/Uint8Array longer than 125 bytes. The byte length is computed via Buffer.byteLength (strings), data.size (Blobs), or data.length (buffers) at sender.js:243-253.

Common situations: Using ping as an application-level heartbeat carrying a large timestamp or correlation ID; echoing back a pong payload that was originally oversized; debugging by pinging with a long string; sending a binary ping from a Buffer that grew unexpectedly.

Related errors

• The message must not be greater than 123 bytes
• Unexpected end of input
• An invalid or duplicated subprotocol was specified
• First argument must be a valid error code number
• Invalid URL

AI-assisted analysis of websockets/ws@c791e707ea (2026-08-06). Data as JSON: /api/errors/a8313866d5a82416. Report an issue: GitHub.

Appendix: 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 c791e707ea)