earendil-works/pi · error · TypeError

PiServer Unix socket mode must be an integer between 0 and…

Error message

PiServer Unix socket mode must be an integer between 0 and 0o777

What it means

Option-validation TypeError from resolveUnixListenerOptions: the resolved `mode` value (options.mode, defaulting to DEFAULT_SOCKET_MODE) that will be chmod'd onto the Unix socket is not an integer in the octal permission range 0–0o777. The listener is constructed with an unusable permission mask, so it fails fast before any filesystem or bind side effects.

Solutions

1. Set the Unix socket mode to an integer between 0 and 0o777.

When it happens

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

Common situations: See trigger scenarios.

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

Appendix: source

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

			if (error) reportError(error);
			resolve();
		});
	});
}

function isErrorCode(error: unknown, code: string): boolean {
	return error instanceof Error && "code" in error && error.code === code;
}

export function createUnixListener(options: UnixListenerOptions): PiServerListener {
	return new UnixListener(options);
}

function resolveUnixListenerOptions(options: UnixListenerOptions): ResolvedUnixListenerOptions {
	validateUnixSocketPath(options.path, "PiServer Unix socket path");
	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 {

View on GitHub (pinned to 4af9d21d3b)