earendil-works/pi · error · TypeError

PiServer gracefulCloseTimeoutMs must be an integer between…

Error message

PiServer gracefulCloseTimeoutMs must be an integer between 1 and ${MAX_TIMER_DELAY_MS}

What it means

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.

Solutions

Set gracefulCloseTimeoutMs to an integer within the allowed timer range.

Defensive patterns

Strategy: validation

When it happens

Trigger: Thrown at packages/server/src/transports/unix/listener.ts:425 when the library encounters an invalid state.

Common situations: See trigger scenarios.

Understand the failure class

Timeouts: ETIMEDOUT, deadlines, and hung requests — what actually expires when a request times out.

AI-assisted analysis of earendil-works/pi@4af9d21d3b (2026-08-24). Data as JSON: /api/errors/a5e36abec02acb18. Report an issue: GitHub.

Appendix: source

Thrown at packages/server/src/transports/unix/listener.ts:425

	const mode = options.mode ?? DEFAULT_SOCKET_MODE;
	if (!Number.isInteger(mode) || mode < 0 || mode > 0o777) {
		throw new TypeError("PiServer Unix socket mode must be an integer between 0 and 0o777");
	}
	const maxFrameLength = options.maxFrameLength ?? DEFAULT_MAX_FRAME_LENGTH;
	if (!Number.isSafeInteger(maxFrameLength) || maxFrameLength <= 0 || maxFrameLength > MAX_UINT32) {
		throw new TypeError(`PiServer maxFrameLength must be an integer between 1 and ${MAX_UINT32}`);
	}
	const maxPendingBytes = options.maxPendingBytes ?? maxFrameLength * 4;
	if (!Number.isSafeInteger(maxPendingBytes) || maxPendingBytes < maxFrameLength + 4) {
		throw new TypeError("PiServer maxPendingBytes must be a safe integer at least maxFrameLength + 4");
	}
	const gracefulCloseTimeoutMs = options.gracefulCloseTimeoutMs ?? DEFAULT_GRACEFUL_CLOSE_TIMEOUT_MS;
	if (
		!Number.isSafeInteger(gracefulCloseTimeoutMs) ||
		gracefulCloseTimeoutMs <= 0 ||
		gracefulCloseTimeoutMs > MAX_TIMER_DELAY_MS
	) {
		throw new TypeError(`PiServer gracefulCloseTimeoutMs must be an integer between 1 and ${MAX_TIMER_DELAY_MS}`);
	}
	return {
		path: options.path,
		mode,
		maxPendingBytes,
		gracefulCloseTimeoutMs,
		onError: options.onError,
	};
}

View on GitHub (pinned to 4af9d21d3b)