earendil-works/pi · error · Error

Unix listener path changed during cleanup; preserved replace

Error message

Unix listener path changed during cleanup; preserved replacement at ${preserved}

What it means

Error "Unix listener path changed during cleanup; preserved replacement at ${preserved}" thrown in earendil-works/pi.

Source

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

		const preserved = join(dirname(this.path), `.c-${randomUUID().slice(0, 6)}`);
		try {
			await rename(this.path, preserved);
		} catch (error) {
			if (isErrorCode(error, "ENOENT")) return;
			throw error;
		}
		const moved = await lstat(preserved);
		if (moved.isSocket() && moved.dev === identity.dev && moved.ino === identity.ino) {
			await removePath(preserved);
			return;
		}
		try {
			await lstat(this.path);
		} catch (error) {
			if (isErrorCode(error, "ENOENT")) await rename(preserved, this.path);
			else throw error;
		}
		throw new Error(`Unix listener path changed during cleanup; preserved replacement at ${preserved}`);
	}

	private reportError(error: unknown): void {
		try {
			this.options.onError?.(error instanceof Error ? error : new Error(String(error)));
		} catch {
			// Error observers cannot affect listener state.
		}
	}
}

/** @internal Exported only for transport-level verification. */
export class UnixByteConnection implements ByteConnection {
	private readonly socket: Socket;
	private readonly gracefulCloseTimeoutMs: number;
	private readonly maxPendingBytes: number;
	private pendingBytes = 0;
	private closedValue = false;

View on GitHub (pinned to 4af9d21d3b)

Solutions

1. Another process replaced the socket during cleanup; investigate concurrent listeners on the same path.

When it happens

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