earendil-works/pi · error · TypeError

${description} is too long; maximum is ${MAX_UNIX_SOCKET_PAT

Error message

${description} is too long; maximum is ${MAX_UNIX_SOCKET_PATH_BYTES} UTF-8 bytes

What it means

Error "${description} is too long; maximum is ${MAX_UNIX_SOCKET_PATH_BYTES} UTF-8 bytes" thrown in earendil-works/pi.

Source

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

import { chmod, link, lstat, mkdir, rename, unlink } from "node:fs/promises";
import { createConnection, createServer, type Server, type Socket } from "node:net";
import { dirname, join } from "node:path";
import { DEFAULT_MAX_FRAME_LENGTH } from "@earendil-works/pi-protocol";
import type { ByteConnection, ByteConnectionAcceptor } from "../../connection.ts";
import type { PiServerListener } from "../../listener.ts";
import type { UnixListenerOptions } from "./types.ts";

const DEFAULT_SOCKET_MODE = 0o600;
const DEFAULT_GRACEFUL_CLOSE_TIMEOUT_MS = 5_000;
const MAX_UINT32 = 0xffff_ffff;
const MAX_TIMER_DELAY_MS = 2_147_483_647;
const SOCKET_PROBE_TIMEOUT_MS = 1_000;
const MAX_UNIX_SOCKET_PATH_BYTES = process.platform === "linux" ? 107 : 103;

export function validateUnixSocketPath(path: string, description = "Unix socket path"): void {
	if (!path) throw new TypeError(`${description} must not be empty`);
	if (Buffer.byteLength(path) > MAX_UNIX_SOCKET_PATH_BYTES) {
		throw new TypeError(`${description} is too long; maximum is ${MAX_UNIX_SOCKET_PATH_BYTES} UTF-8 bytes`);
	}
}

interface ResolvedUnixListenerOptions {
	path: string;
	mode: number;
	gracefulCloseTimeoutMs: number;
	maxPendingBytes: number;
	onError?: (error: Error) => void;
}

interface FileIdentity {
	dev: number;
	ino: number;
}
class UnixListener implements PiServerListener {
	private readonly options: ResolvedUnixListenerOptions;
	private readonly path: string;

View on GitHub (pinned to 4af9d21d3b)

Solutions

1. Shorten the socket path to fit the platform's Unix socket path limit.

When it happens

Trigger: Thrown at packages/server/src/transports/unix/listener.ts:21 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/074ddc74c751468a. Report an issue: GitHub.