earendil-works/pi · error · Error

Refusing to remove non-socket Unix listener path

Error message

Refusing to remove non-socket Unix listener path: ${path}

What it means

Safety guard in removeStaleSocket: the filesystem entry at the requested Unix socket path exists (lstat succeeded) but lstat reports it is not a socket file (e.g. a regular file or directory). The stale-socket cleanup refuses to delete an entry it did not create rather than blindly unlinking a foreign object.

Solutions

1. The path is not a socket; remove it manually or point the listener elsewhere.

When it happens

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

Appendix: source

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

			}
		});
	}
}

function getOwnedBindPath(path: string): string {
	const suffix = createHash("sha256").update(path).digest("hex").slice(0, 8);
	return join(dirname(path), `.p-${suffix}`);
}

async function removeStaleSocket(path: string): Promise<void> {
	let original: Stats;
	try {
		original = await lstat(path);
	} catch (error) {
		if (isErrorCode(error, "ENOENT")) return;
		throw error;
	}
	if (!original.isSocket()) throw new Error(`Refusing to remove non-socket Unix listener path: ${path}`);
	if (await isSocketLive(path)) throw new Error(`Unix listener is already running: ${path}`);

	const preserved = join(dirname(path), `.s-${randomUUID().slice(0, 6)}`);
	try {
		await rename(path, preserved);
	} catch (error) {
		if (isErrorCode(error, "ENOENT")) return;
		throw error;
	}
	const current = await lstat(preserved);
	if (!current.isSocket() || current.dev !== original.dev || current.ino !== original.ino) {
		try {
			await lstat(path);
		} catch (error) {
			if (isErrorCode(error, "ENOENT")) await rename(preserved, path);
			else throw error;
		}
		throw new Error(`Unix listener path changed while checking for a stale socket: ${path}`);

View on GitHub (pinned to 4af9d21d3b)