{"record":{"id":"a5e36abec02acb18","repo":"earendil-works/pi","slug":"piserver-gracefulclosetimeoutms-must-be-an-integer","errorCode":null,"errorMessage":"PiServer gracefulCloseTimeoutMs must be an integer between 1 and ${MAX_TIMER_DELAY_MS}","messagePattern":"PiServer gracefulCloseTimeoutMs must be an integer between 1 and (.+?)","errorType":"validation","errorClass":"TypeError","httpStatus":null,"severity":"error","filePath":"packages/server/src/transports/unix/listener.ts","lineNumber":425,"sourceCode":"\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":407,"sourceCodeEnd":435,"githubUrl":"https://github.com/earendil-works/pi/blob/4af9d21d3b4d664e4a29fcabfec85171077248e3/packages/server/src/transports/unix/listener.ts#L407-L435","documentation":"Option-validation TypeError from resolveUnixListenerOptions: gracefulCloseTimeoutMs (options.gracefulCloseTimeoutMs) is not a safe integer within 1..MAX_TIMER_DELAY_MS, the range Node.js timers can actually schedule. An unusable close timeout would break shutdown draining, so the UnixListener constructor rejects it up front.","triggerScenarios":"Thrown at packages/server/src/transports/unix/listener.ts:425 when the library encounters an invalid state.","commonSituations":"See trigger scenarios.","solutions":["Set gracefulCloseTimeoutMs to an integer within the allowed timer range."],"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"}