earendil-works/pi · error · TypeError

PiServer handshakeTimeoutMs must be an integer between 1 and

Error message

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

What it means

Error "PiServer handshakeTimeoutMs must be an integer between 1 and ${MAX_TIMER_DELAY_MS}" thrown in earendil-works/pi.

Source

Thrown at packages/server/src/server.ts:393

			// Error observers cannot affect server state.
		}
	}
}

function resolveOptions(options: PiServerOptions): { maxFrameLength: number; handshakeTimeoutMs: number } {
	if (!Array.isArray(options.listeners)) throw new TypeError("PiServer listeners must be an array");
	if (options.serverId === "") throw new TypeError("PiServer serverId must not be empty");
	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 handshakeTimeoutMs = options.handshakeTimeoutMs ?? DEFAULT_HANDSHAKE_TIMEOUT_MS;
	if (
		!Number.isSafeInteger(handshakeTimeoutMs) ||
		handshakeTimeoutMs <= 0 ||
		handshakeTimeoutMs > MAX_TIMER_DELAY_MS
	) {
		throw new TypeError(`PiServer handshakeTimeoutMs must be an integer between 1 and ${MAX_TIMER_DELAY_MS}`);
	}
	return { maxFrameLength, handshakeTimeoutMs };
}

View on GitHub (pinned to 4af9d21d3b)

Solutions

1. Set handshakeTimeoutMs to an integer within the allowed timer range.

When it happens

Trigger: Thrown at packages/server/src/server.ts:393 when the library encounters an invalid state.

Common situations: See trigger scenarios.

Understand the failure class

• SSL/TLS and certificate errors — how TLS handshakes and certificate validation fail.
• 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/c455fc08be80a0a9. Report an issue: GitHub.