can1357/oh-my-pi · error · Error

Python kernel unavailable

Error message

Python kernel unavailable

What it means

ensureKernelAvailable probes the Python environment (checkPythonKernelAvailability: enumerating runtimes and spawning each candidate with `python -c "import sys;sys.exit(0)"`). If the probe returns !ok — no interpreter on PATH, the probe subprocess failed, or it was aborted — this generic Error is thrown with the probe's reason, defaulting to 'Python kernel unavailable'. It fails fast before any cell executes.

Source

Thrown at packages/coding-agent/src/eval/py/executor.ts:337

		code,
		options,
		runIdPrefix: "py",
		errorLogLabel: "Python",
		cancelledErrorClass: PythonExecutionCancelledError,
		buildKernelEnvPatch: buildManagedKernelEnvPatch,
		formatKernelTimeoutAnnotation,
		formatTimeoutAnnotation,
	});
}

async function ensureKernelAvailable(cwd: string, options: PythonExecutorOptions): Promise<void> {
	const availability = await waitForPromiseWithCancellation(
		checkPythonKernelAvailability(cwd, options.interpreter),
		options,
		PythonExecutionCancelledError,
	);
	if (!availability.ok) {
		throw new Error(availability.reason ?? "Python kernel unavailable");
	}
}

async function ensureToolBridge(options: PythonExecutorOptions): Promise<void> {
	if (!options.toolSession || options.bridge) return;
	try {
		options.bridge = await ensurePyToolBridge();
	} catch (err) {
		logger.warn("Failed to start Python tool bridge", {
			error: err instanceof Error ? err.message : String(err),
		});
	}
}

async function executePerCall(code: string, cwd: string, options: PythonExecutorOptions): Promise<PythonResult> {
	if (options.bridge && !options.bridgeSessionId) {
		options.bridgeSessionId = `py-bridge:${crypto.randomUUID()}`;
	}

View on GitHub (pinned to 9690622007)

Solutions

1. Install Python or fix PATH so `python`/`python3` resolves in the executor's shell environment.
2. Pass options.interpreter with an absolute path to a working interpreter (e.g. .venv/bin/python).
3. Recreate the virtualenv if its python binary is missing/broken.
4. Read availability.reason in the thrown message — it names the concrete failure (e.g. 'Python executable not found on PATH').

Example fix

// before
await executePython(cwd, code); // relies on PATH
// after
await executePython(cwd, code, { interpreter: "/path/to/project/.venv/bin/python" });

const which = Bun.spawnSync(["python3", "-c", "import sys;sys.exit(0)"]); if (!which.success) throw new Error('No working python3 on PATH; install Python or pass options.interpreter');

function isKernelUnavailable(e: unknown): e is Error { return e instanceof Error && /Python kernel unavailable|not found on PATH/.test(e.message); }

try {
  await ensureKernelAvailable(options);
} catch (err) {
  if (err instanceof Error && err.message.startsWith('Python kernel unavailable')) {
    // fall back to an explicit interpreter or fail the run with a setup hint
  } else throw err;
}

When it happens

Trigger: executePython with a cwd that has no resolvable Python interpreter, a broken interpreter configured via options.interpreter, a venv whose python binary is missing, PATH not containing python/python3 in the shell env, or the availability probe being cancelled/timed out.

Common situations: Running evals in a container/CI image without Python installed; a deleted or recreated .venv; specifying an interpreter path that doesn't exist; PATH stripped in non-interactive shells; pyenv shim pointing at an uninstalled version.

Related errors

• Python kernel unavailable
• Python executable not found on PATH
• Could not resolve ${APP_NAME} binary path in PATH
• 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/de308a0fbb54b012. Report an issue: GitHub.