{"record":{"id":"1fb4eff6a15856eb","repo":"earendil-works/pi","slug":"piserver-maxpendingbytes-must-be-a-safe-integer-at","errorCode":null,"errorMessage":"PiServer maxPendingBytes must be a safe integer at least maxFrameLength + 4","messagePattern":"PiServer maxPendingBytes must be a safe integer at least maxFrameLength \\+ 4","errorType":"validation","errorClass":"TypeError","httpStatus":null,"severity":"error","filePath":"packages/server/src/transports/unix/listener.ts","lineNumber":417,"sourceCode":"}\n\nexport function createUnixListener(options: UnixListenerOptions): PiServerListener {\n\treturn new UnixListener(options);\n}\n\nfunction resolveUnixListenerOptions(options: UnixListenerOptions): ResolvedUnixListenerOptions {\n\tvalidateUnixSocketPath(options.path, \"PiServer Unix socket path\");\n\tconst mode = options.mode ?? DEFAULT_SOCKET_MODE;\n\tif (!Number.isInteger(mode) || mode < 0 || mode > 0o777) {\n\t\tthrow new TypeError(\"PiServer Unix socket mode must be an integer between 0 and 0o777\");\n\t}\n\tconst maxFrameLength = options.maxFrameLength ?? DEFAULT_MAX_FRAME_LENGTH;\n\tif (!Number.isSafeInteger(maxFrameLength) || maxFrameLength <= 0 || maxFrameLength > MAX_UINT32) {\n\t\tthrow new TypeError(`PiServer maxFrameLength must be an integer between 1 and ${MAX_UINT32}`);\n\t}\n\tconst maxPendingBytes = options.maxPendingBytes ?? maxFrameLength * 4;\n\tif (!Number.isSafeInteger(maxPendingBytes) || maxPendingBytes < maxFrameLength + 4) {\n\t\tthrow new TypeError(\"PiServer maxPendingBytes must be a safe integer at least maxFrameLength + 4\");\n\t}\n\tconst gracefulCloseTimeoutMs = options.gracefulCloseTimeoutMs ?? DEFAULT_GRACEFUL_CLOSE_TIMEOUT_MS;\n\tif (\n\t\t!Number.isSafeInteger(gracefulCloseTimeoutMs) ||\n\t\tgracefulCloseTimeoutMs <= 0 ||\n\t\tgracefulCloseTimeoutMs > MAX_TIMER_DELAY_MS\n\t) {\n\t\tthrow new TypeError(`PiServer gracefulCloseTimeoutMs must be an integer between 1 and ${MAX_TIMER_DELAY_MS}`);\n\t}\n\treturn {\n\t\tpath: options.path,\n\t\tmode,\n\t\tmaxPendingBytes,\n\t\tgracefulCloseTimeoutMs,\n\t\tonError: options.onError,\n\t};\n}\n","sourceCodeStart":399,"sourceCodeEnd":435,"githubUrl":"https://github.com/earendil-works/pi/blob/4af9d21d3b4d664e4a29fcabfec85171077248e3/packages/server/src/transports/unix/listener.ts#L399-L435","documentation":"Option-validation TypeError from resolveUnixListenerOptions: maxPendingBytes (options.maxPendingBytes or the maxFrameLength*4 default) is not a safe integer or is smaller than maxFrameLength + 4, meaning the buffering budget could not even hold a single maximal frame plus its header — a contradiction that would make backpressure logic unable to function.","triggerScenarios":"Thrown at packages/server/src/transports/unix/listener.ts:417 when the library encounters an invalid state.","commonSituations":"See trigger scenarios.","solutions":["Set maxPendingBytes to a safe integer of at least maxFrameLength + 4."],"exampleFix":null,"handlingStrategy":"validation","validationCode":null,"typeGuard":null,"tryCatchPattern":null,"preventionTips":[],"tags":[],"backgroundTag":null,"analyzedSha":"4af9d21d3b4d664e4a29fcabfec85171077248e3","analyzedAt":"2026-08-24T13:07:14.692Z","contentChangedAt":null,"schemaVersion":2},"datasetVersion":"2026-09-23T08:17:48.524Z"}