can1357/oh-my-pi · error · Error

Adapter process exited before TCP port ${host}:${port} was r

Error message

Adapter process exited before TCP port ${host}:${port} was ready

What it means

While waiting for a TCP-mode DAP adapter to start listening on host:port, the launcher observes the adapter process has exited. Since a dead process can never open the port, this error is thrown immediately rather than continuing to poll until the generic port-timeout fires.

Source

Thrown at packages/coding-agent/src/dap/client.ts:852

		},
	}).catch(error => {
		onClose?.();
		reject(error);
	});
	return promise;
}

/** Wait for a TCP DAP server and retain the first successful connection. */
async function waitForTcpTransport(
	host: string,
	port: number,
	timeoutMs: number,
	proc: { exitCode: number | null },
): Promise<SocketTransport> {
	const deadline = Date.now() + timeoutMs;
	while (Date.now() < deadline) {
		if (proc.exitCode !== null) {
			throw new Error(`Adapter process exited before TCP port ${host}:${port} was ready`);
		}
		try {
			return await connectTcpSocket(host, port);
		} catch {
			await Bun.sleep(50);
		}
	}
	throw new Error(`TCP port ${host}:${port} was not ready after ${timeoutMs}ms`);
}

/**
 * Give the adapter a chance to announce it is listening on `port` before the
 * first connect. vscode-js-debug prints `Debug server listening at HOST:PORT`
 * to stdout from inside its `listen()` callback; waiting for the port to appear
 * there means we only connect once the child genuinely owns the reserved port,
 * which closes the WSL2-mirrored ghost-accept window (issue #6055) at its root.
 *
 * Best-effort: resolves on the banner, on process exit, or on timeout — the

View on GitHub (pinned to 9690622007)

Solutions

Run the adapter's server command manually with the same host/port to capture its exit error
Fix adapter server flags/port configuration in the adapter descriptor or debug config
Check for port conflicts (another process bound to the port) and pick a free port
Capture adapter stderr at launch and check logs for the crash reason

Example fix

// before
args: ['--server=4711', '--unknown-flag'] // adapter exits
// after
args: ['--server=4711'] // verified manually: node dbg.js --server=4711

Defensive patterns

Strategy: try-catch

Validate before calling

const listening = await new Response(proc.stdout).text().then(t => t.includes('listening'));
if (!listening && proc.exitCode !== null) throw new Error('adapter exited before listening');

Try / catch

try {
  await connectTcpPort(adapter, host, port, timeoutMs, proc);
} catch (err) {
  if (String((err as Error).message).includes('exited before TCP port')) {
    console.error(`adapter ${adapter.name} died on startup; check its stderr and server flags`);
  }
  throw err;
}

Prevention

Verify the adapter's TCP server flags (--server/--port) against its documented CLI
Check the configured port is free before launch (lsof/ss)
Keep adapter stderr captured; startup exits are almost always logged there
Use an adapter version whose server mode matches your config schema

When it happens

Trigger: Adapter launched with a --server/--port TCP mode crashes at startup (bad args, missing runtime, port binding failure causing exit); the listen command exits because the configured port is invalid or privileged; adapter binary fails before entering its listen loop.

Common situations: Typo'd or incompatible adapter server flags; port already in use making the adapter abort; node/python runtime version mismatch for the TCP debug server; adapter crashing on invalid launch configuration JSON.

Related errors

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