{"record":{"id":"21fd53d0970da278","repo":"websockets/ws","slug":"first-argument-must-be-a-valid-error-code-number","errorCode":null,"errorMessage":"First argument must be a valid error code number","messagePattern":"First argument must be a valid error code number","errorType":"exception","errorClass":"TypeError","httpStatus":null,"severity":"error","filePath":"lib/sender.js","lineNumber":190,"sourceCode":"    return [target, data];\n  }\n\n  /**\n   * Sends a close message to the other peer.\n   *\n   * @param {Number} [code] The status code component of the body\n   * @param {(String|Buffer)} [data] The message component of the body\n   * @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 {","sourceCodeStart":172,"sourceCodeEnd":208,"githubUrl":"https://github.com/websockets/ws/blob/c791e707eab3c13dd9a261d2479c3cc4a49a6fed/lib/sender.js#L172-L208","documentation":"Thrown (as TypeError) by `Sender.close()` when the `code` argument is provided but is not a number, or is a number that fails `isValidStatusCode()`. Per RFC 6455 §7.4, the only valid status codes are 1000–1014 (excluding the reserved 1004, 1005, and 1006) and the application range 3000–4999. Codes 1005/1006 must never be sent on the wire (they are generated internally), and 1004 is undefined/unused, so the library rejects them.","triggerScenarios":"Calling `ws.close(999, 'reason')` (below range), `ws.close(1005)` (reserved, must not be sent), `ws.close(2000, 'reason')` (outside 3000–4999), `ws.close('1000')` (string not number), or `ws.close(undefined, 'reason')` passed through carelessly.","commonSituations":"Passing a string status code from a config/env var without coercion; using a 'magic' code outside the defined ranges; copy-pasting a code that is reserved (1004/1005/1006); passing a close code from the wrong end of a mapping table.","solutions":["Use a defined code: 1000 (normal closure), 1001 (going away), 1002 (protocol error), 1003 (unsupported data), 1007–1011, or a custom 3000–4999.","Coerce string inputs to numbers and check the range before calling `close()`.","Omit `code` (and `reason`) entirely to send a close frame with no status code — `ws.close()` is always valid."],"exampleFix":"// before\nws.close(999, 'done');\n\n// after\nws.close(1000, 'done');","handlingStrategy":"validation","validationCode":"// Validate a close code before calling ws.close().\nfunction isValidStatusCode(code) {\n  return (\n    (code >= 1000 &&\n      code <= 1014 &&\n      code !== 1004 &&\n      code !== 1005 &&\n      code !== 1006) ||\n    (code >= 3000 && code <= 4999)\n  );\n}\nfunction safeClose(ws, code, reason) {\n  if (code === undefined) return ws.close();\n  if (typeof code !== 'number' || !isValidStatusCode(code)) return ws.close();\n  return ws.close(code, reason);\n}","typeGuard":"function isValidCloseCode(code) {\n  return (\n    typeof code === 'number' &&\n    Number.isInteger(code) &&\n    ((code >= 1000 &&\n      code <= 1014 &&\n      code !== 1004 &&\n      code !== 1005 &&\n      code !== 1006) ||\n      (code >= 3000 && code <= 4999))\n  );\n}","tryCatchPattern":"try {\n  ws.close(maybeCode, reason);\n} catch (err) {\n  if (err instanceof TypeError && /valid error code/.test(err.message)) {\n    // Fall back to a code-less close frame.\n    ws.close();\n    return;\n  }\n  throw err;\n}","preventionTips":["Always pass an integer in 1000–1014 (not 1004/1005/1006) or 3000–4999, or omit the code entirely.","Coerce status codes read from config/env to numbers and validate the range before calling `close()`.","Wrap programmatic `close()` calls in a helper that validates the code, so a bad value degrades to a code-less close."],"tags":["websocket","close","status-code","protocol","rfc6455"],"backgroundTag":null,"analyzedSha":"c791e707eab3c13dd9a261d2479c3cc4a49a6fed","analyzedAt":"2026-08-06T19:07:51.047Z","contentChangedAt":null,"schemaVersion":2},"datasetVersion":"2026-09-23T08:17:48.524Z"}