{"record":{"id":"a8313866d5a82416","repo":"websockets/ws","slug":"the-data-size-must-not-be-greater-than-125-bytes","errorCode":null,"errorMessage":"The data size must not be greater than 125 bytes","messagePattern":"The data size must not be greater than 125 bytes","errorType":"exception","errorClass":"RangeError","httpStatus":null,"severity":"error","filePath":"lib/sender.js","lineNumber":256,"sourceCode":"   */\n  ping(data, mask, cb) {\n    let byteLength;\n    let readOnly;\n\n    if (typeof data === 'string') {\n      byteLength = Buffer.byteLength(data);\n      readOnly = false;\n    } else if (isBlob(data)) {\n      byteLength = data.size;\n      readOnly = false;\n    } else {\n      data = toBuffer(data);\n      byteLength = data.length;\n      readOnly = toBuffer.readOnly;\n    }\n\n    if (byteLength > 125) {\n      throw new RangeError('The data size must not be greater than 125 bytes');\n    }\n\n    const options = {\n      [kByteLength]: byteLength,\n      fin: true,\n      generateMask: this._generateMask,\n      mask,\n      maskBuffer: this._maskBuffer,\n      opcode: 0x09,\n      readOnly,\n      rsv1: false\n    };\n\n    if (isBlob(data)) {\n      if (this._state !== DEFAULT) {\n        this.enqueue([this.getBlobData, data, false, options, cb]);\n      } else {\n        this.getBlobData(data, false, options, cb);","sourceCodeStart":238,"sourceCodeEnd":274,"githubUrl":"https://github.com/websockets/ws/blob/c791e707eab3c13dd9a261d2479c3cc4a49a6fed/lib/sender.js#L238-L274","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","solutions":["Keep ping payloads small: use a short monotonic counter or timestamp (e.g. Buffer.allocUnsafe(8) or a short string), staying under 125 bytes.","If you need to send larger keepalive data, use ws.send(data, { binary: true }) instead of ws.ping().","Truncate or omit the data: ws.ping() with no argument sends an empty ping, which is sufficient for most liveness checks."],"exampleFix":"// before\nws.ping(Buffer.alloc(200));\n\n// after\nws.ping(); // empty ping is enough for liveness\n// or, if you need a nonce:\nws.ping(crypto.randomBytes(8));","handlingStrategy":"validation","validationCode":"function pingSize(data) {\n  if (data == null) return 0;\n  if (typeof data === 'string') return Buffer.byteLength(data);\n  if (typeof data === 'object' && typeof data.size === 'number') return data.size; // Blob\n  return data.length;\n}\n// usage: if (pingSize(data) <= 125) ws.ping(data);","typeGuard":"function isPingSafe(data) {\n  const len = data == null ? 0\n    : typeof data === 'string' ? Buffer.byteLength(data)\n    : typeof data.size === 'number' ? data.size\n    : data.length;\n  return len <= 125;\n}","tryCatchPattern":"try {\n  ws.ping(data);\n} catch (err) {\n  if (err instanceof RangeError && /125 bytes/.test(err.message)) {\n    // payload too large; send empty ping or a data message instead\n    ws.ping();\n  } else throw err;\n}","preventionTips":["Keep ping payloads tiny (a counter or short nonce); use ws.send() for larger keepalive data.","Call ws.ping() with no argument for a simple liveness check.","Validate byte length before calling if payload size is variable."],"tags":["websocket","ping","control-frame","rfc6455","validation"],"backgroundTag":null,"analyzedSha":"c791e707eab3c13dd9a261d2479c3cc4a49a6fed","analyzedAt":"2026-08-06T19:07:51.047Z","contentChangedAt":null,"schemaVersion":2},"datasetVersion":"2026-09-23T08:17:48.524Z"}