can1357/oh-my-pi · error · Error

Python kernel unavailable

Error message

Python kernel unavailable

What it means

PythonKernel.start probes availability (checkPythonKernelAvailability) before spawning the kernel process; if the probe fails — no Python runtime found, all candidates failed to spawn, or the probe was cancelled — it throws this Error carrying the probe's specific reason (default 'Python kernel unavailable'). It guards against starting a kernel on a broken Python environment.

Source

Thrown at packages/coding-agent/src/eval/py/kernel.ts:151

					id: msgId,
					code,
					cwd: opts?.cwd,
					env: opts?.env,
					silent: opts?.silent ?? false,
					storeHistory: opts?.storeHistory ?? !(opts?.silent ?? false),
				}),
		});
	}

	static async start(options: KernelStartOptions): Promise<PythonKernel> {
		const availability = await logger.time(
			"PythonKernel.start:availabilityCheck",
			checkPythonKernelAvailability,
			options.cwd,
			options.interpreter,
		);
		if (!availability.ok) {
			throw new Error(availability.reason ?? "Python kernel unavailable");
		}

		let runtime = availability.runtime;
		if (!runtime) {
			const { env: shellEnv } = (await Settings.init()).getShellConfig();
			runtime = options.interpreter
				? resolveExplicitPythonRuntime(options.interpreter, options.cwd, filterEnv(shellEnv))
				: resolvePythonRuntime(options.cwd, filterEnv(shellEnv));
		}
		const spawnEnv: Record<string, string> = {};
		for (const [key, value] of Object.entries(runtime.env)) {
			if (typeof value === "string") spawnEnv[key] = value;
		}
		for (const [key, value] of Object.entries(options.env ?? {})) {
			if (typeof value === "string") spawnEnv[key] = value;
		}
		spawnEnv.PYTHONUNBUFFERED = "1";
		spawnEnv.PYTHONIOENCODING = "utf-8";

View on GitHub (pinned to 9690622007)

Solutions

1. Install Python or correct PATH in the shell environment used by the settings' shell config.
2. Pass an explicit, existing interpreter path via options.interpreter.
3. If the reason is a cancelled probe, retry with a longer probe timeout / without an aborting signal.
4. Failures aren't cached — fixing the environment is picked up on the next start attempt.

Example fix

// before
const kernel = new PythonKernel({ cwd, interpreter: "python3.13" }); // not installed
await kernel.start();
// after
const kernel = new PythonKernel({ cwd, interpreter: "/usr/bin/python3" }); // exists
await kernel.start();

const probe = Bun.spawnSync([interpreter ?? "python3", "--version"]); if (!probe.success) throw new Error(`Interpreter ${interpreter ?? 'python3'} is not runnable`);

function isKernelStartError(e: unknown): e is Error { return e instanceof Error && e.message.includes('Python kernel unavailable'); }

try {
  await kernel.start();
} catch (err) {
  if (err instanceof Error && err.message.includes('Python kernel unavailable')) {
    // inspect err.message for the concrete probe reason and fix the environment
  } else throw err;
}

When it happens

Trigger: Starting a kernel with options.cwd containing no Python on PATH, an invalid options.interpreter, a shell env whose PATH lacks Python (Settings.getShellConfig env), or the probe being aborted via its signal/timeout.

Common situations: First eval run in a fresh container without Python; a misconfigured shell profile stripping PATH; a deleted venv; interpreter pointing at a nonexistent binary; probe timeouts on very slow machines.

Related errors

• Python kernel unavailable
• Command aborted
• Command timed out
• Protocol paths are not supported by this helper: {path}
• No session - output artifacts unavailable

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