{"id":"bcc03068003ec1f3","repo":"websockets/ws","slug":"the-message-must-not-be-greater-than-123-bytes","errorCode":null,"errorMessage":"The message must not be greater than 123 bytes","messagePattern":"The message must not be greater than 123 bytes","errorType":"exception","errorClass":"RangeError","httpStatus":null,"severity":"error","filePath":"lib/sender.js","lineNumber":198,"sourceCode":"   * @param {Boolean} [mask=false] Specifies whether or not to mask the message\n   * @param {Function} [cb] Callback\n   * @public\n   */\n  close(code, data, mask, cb) {\n    let buf;\n\n    if (code === undefined) {\n      buf = EMPTY_BUFFER;\n    } else if (typeof code !== 'number' || !isValidStatusCode(code)) {\n      throw new TypeError('First argument must be a valid error code number');\n    } else if (data === undefined || !data.length) {\n      buf = Buffer.allocUnsafe(2);\n      buf.writeUInt16BE(code, 0);\n    } else {\n      const length = Buffer.byteLength(data);\n\n      if (length > 123) {\n        throw new RangeError('The message must not be greater than 123 bytes');\n      }\n\n      buf = Buffer.allocUnsafe(2 + length);\n      buf.writeUInt16BE(code, 0);\n\n      if (typeof data === 'string') {\n        buf.write(data, 2);\n      } else if (isUint8Array(data)) {\n        buf.set(data, 2);\n      } else {\n        throw new TypeError('Second argument must be a string or a Uint8Array');\n      }\n    }\n\n    const options = {\n      [kByteLength]: buf.length,\n      fin: true,\n      generateMask: this._generateMask,","sourceCodeStart":180,"sourceCodeEnd":216,"githubUrl":"https://github.com/websockets/ws/blob/ae1de54330cef77e487548890fabfeb9aae1d83d/lib/sender.js#L180-L216","documentation":"Thrown by Sender.close() when the optional 'data' (reason) argument passed alongside a numeric status code exceeds 123 bytes. The WebSocket close frame is a control frame, which RFC 6455 limits to 125 bytes of payload; 2 bytes are reserved for the status code, leaving at most 123 bytes for the reason text. The library enforces this in lib/sender.js:197-199 by measuring Buffer.byteLength(data) before constructing the frame.","triggerScenarios":"Calling ws.close(code, data) or ws.terminate()'s sibling ws.close() with a status code and a reason string (or Uint8Array) whose byte length exceeds 123. Internally, Sender.close(code, data, mask, cb) computes const length = Buffer.byteLength(data); and throws RangeError when length > 123. This also propagates from WebSocket.close() (websocket.js:322) which forwards code and data to the sender.","commonSituations":"Developers pasting long human-readable error descriptions or stack traces as the close reason; embedding JSON diagnostics into the close payload; localized multi-byte UTF-8 messages (e.g. CJK text) that are short in characters but exceed 123 bytes.","solutions":["Truncate or shorten the reason so Buffer.byteLength(reason) <= 123 (remember multi-byte UTF-8 chars count more than one byte).","If you need to send more context, deliver it in a final application message before calling close().","Pass only a status code with no data argument (ws.close(code)) if the reason is non-essential."],"exampleFix":"// before\nws.close(1000, veryLongErrorStack); // > 123 bytes\n\n// after\nconst reason = veryLongErrorStack.slice(0, 100); // leave headroom for UTF-8\nws.close(1000, reason);","handlingStrategy":"validation","validationCode":"function safeClose(ws, code, reason) {\n  if (reason !== undefined) {\n    const bytes = Buffer.byteLength(reason, 'utf8');\n    if (bytes > 123) {\n      reason = reason.slice(0, Math.max(0, 123 - (bytes - reason.length)));\n      // or, simpler: truncate to a conservative char count\n      while (Buffer.byteLength(reason, 'utf8') > 123) reason = reason.slice(0, -1);\n    }\n  }\n  ws.close(code, reason);\n}","typeGuard":"function isValidCloseReason(data) {\n  return (\n    data === undefined ||\n    typeof data === 'string' ||\n    (data instanceof Uint8Array && Buffer.byteLength(data) <= 123)\n  );\n}","tryCatchPattern":"try {\n  ws.close(code, reason);\n} catch (err) {\n  if (err instanceof RangeError && /must not be greater than 123 bytes/.test(err.message)) {\n    ws.close(code); // retry without oversized reason\n  } else {\n    throw err;\n  }\n}","preventionTips":["Always measure with Buffer.byteLength(reason) because UTF-8 multi-byte chars consume more than one byte.","Treat the close reason as a short status label, not a message transport.","Centralize close() calls behind a helper that enforces the 123-byte limit."],"tags":["websocket","control-frame","rfc-6455","input-validation"],"analyzedSha":"ae1de54330cef77e487548890fabfeb9aae1d83d","analyzedAt":"2026-08-03T19:11:18.437Z","schemaVersion":2}