What causes "LSP mux environment is incomplete" in can1357/oh-my-pi?

Start the mux through the normal path (`omp lsp` / ensureLspMuxDaemon) so it injects LSP_MUX_SOCKET_ENV and LSP_MUX_PROJECT_DIR_ENV.

can1357/oh-my-pi · error

LSP mux environment is incomplete

Error message

LSP mux environment is incomplete

What it means

startLspMuxFromEnvironment() is the entrypoint for the detached mux worker process and requires two environment variables: the socket endpoint and the project directory. It throws this error when either is missing, meaning the process was started as a mux worker without the spawning parent supplying its configuration.

Source

Thrown at packages/coding-agent/src/lsp/mux/server.ts:732

	#disarmMuxIdle(): void {
		if (this.#idleTimer) clearTimeout(this.#idleTimer);
		this.#idleTimer = undefined;
	}

	#armMuxIdle(): void {
		this.#disarmMuxIdle();
		if (this.#shuttingDown || this.#sessions.size > 0) return;
		this.#idleTimer = setTimeout(() => {
			if (this.#sessions.size === 0) this.onIdle?.();
		}, MUX_IDLE_MS);
	}
}

/** Start the detached LSP mux selected by the CLI worker host environment. */
export async function startLspMuxFromEnvironment(): Promise<void> {
	const endpoint = process.env[LSP_MUX_SOCKET_ENV];
	const projectDir = process.env[LSP_MUX_PROJECT_DIR_ENV];
	if (!endpoint || !projectDir) throw new Error("LSP mux environment is incomplete");
	delete process.env[LSP_MUX_SOCKET_ENV];
	delete process.env[LSP_MUX_PROJECT_DIR_ENV];
	setProcessName("omp lsp mux");
	const server = new LspMuxServer();
	const stopped = Promise.withResolvers<void>();
	server.onIdle = () => {
		void server.shutdown().finally(() => {
			stopped.resolve();
			process.exit(0);
		});
	};
	const cancelCleanup = postmortem.register("lsp-mux", () => server.shutdown());
	try {
		await server.listen(endpoint);
		process.stdout.write(`${lspMuxReadyBanner(endpoint)}\n`);
		await stopped.promise;
	} finally {
		cancelCleanup();

View on GitHub (pinned to 9690622007)

Solutions

Start the mux through the normal path (`omp lsp` / ensureLspMuxDaemon) so it injects LSP_MUX_SOCKET_ENV and LSP_MUX_PROJECT_DIR_ENV.
If launching manually, export both env vars before invoking the module: LSP_MUX_SOCKET=/path/sock LSP_MUX_PROJECT_DIR=/path/project.
Check for a bug in the spawn site that drops the env mapping passed to the child.

Example fix

// before
bun packages/coding-agent/src/lsp/mux/server.ts
// after
LSP_MUX_SOCKET=/tmp/omp-lsp.sock LSP_MUX_PROJECT_DIR=$PWD bun packages/coding-agent/src/lsp/mux/server.ts

Defensive patterns

Strategy: validation

Validate before calling

const endpoint = process.env.LSP_MUX_SOCKET;
const projectDir = process.env.LSP_MUX_PROJECT_DIR;
if (!endpoint || !projectDir) throw new Error("Refusing to start mux worker: set LSP_MUX_SOCKET and LSP_MUX_PROJECT_DIR");

Type guard

function hasMuxEnv(env: NodeJS.ProcessEnv): env is NodeJS.ProcessEnv & { LSP_MUX_SOCKET: string; LSP_MUX_PROJECT_DIR: string } {
  return Boolean(env.LSP_MUX_SOCKET && env.LSP_MUX_PROJECT_DIR);
}

Prevention

Always start the mux through ensureLspMuxDaemon / the CLI worker host, not by invoking server.ts directly.
When spawning manually, spread the parent's relevant env into the child.
Log the worker env at spawn time in debug builds to catch dropped variables.

When it happens

Trigger: The CLI worker-host entrypoint dispatches to the LSP mux worker (via the omp worker argv selector) but LSP_MUX_SOCKET_ENV or LSP_MUX_PROJECT_DIR_ENV is unset — e.g. the mux was started directly (`bun server.ts` / `node server.ts`) instead of through ensureLspMuxDaemon.

Common situations: Running the mux server module by hand for debugging without exporting the env vars; a spawned child losing its env; broken worker-host dispatch where the parent forgot to pass the env mapping.

Understand the failure class

Background: "environment variable is not set" and "Missing keys in environment" errors: what missing required env var messages mean and how to fix them — this error's family across 28 libraries.

Related errors

AI-assisted analysis of can1357/oh-my-pi@9690622007 (2026-08-31). Data as JSON: /api/errors/1493971a34b4bfec. Report an issue: GitHub.