can1357/oh-my-pi · critical · Error

Python executable not found on PATH

Error message

Python executable not found on PATH

What it means

resolvePythonRuntime picks the first Python interpreter found by enumeratePythonRuntimes for the given cwd/base environment. If no interpreter exists it throws Error 'Python executable not found on PATH' instead of returning a runtime. enumeratePythonRuntimes is the probing variant; this function is for callers that require an interpreter.

Source

Thrown at packages/coding-agent/src/eval/py/runtime.ts:273

	}

	const systemPath = $which("python") ?? $which("python3");
	if (systemPath) {
		push({ pythonPath: systemPath, env: { ...baseEnv } });
	}

	return runtimes;
}

/**
 * Resolve the highest-priority Python runtime. Prefer {@link enumeratePythonRuntimes}
 * when you can probe candidates; this returns only the first one and throws when
 * no interpreter exists.
 */
export function resolvePythonRuntime(cwd: string, baseEnv: Record<string, string | undefined>): PythonRuntime {
	const [runtime] = enumeratePythonRuntimes(cwd, baseEnv);
	if (!runtime) {
		throw new Error("Python executable not found on PATH");
	}
	return runtime;
}

View on GitHub (pinned to 9690622007)

Solutions

1. Install Python and ensure it is on PATH (python3 on Linux/macOS, python.exe on Windows)
2. Create or repair the virtualenv expected in the project directory
3. Pass a baseEnv whose PATH includes the interpreter's directory, or point the runtime at a known interpreter path
4. Use enumeratePythonRuntimes to probe candidates and fall back to an explicit interpreter path

Example fix

// before
const runtime = resolvePythonRuntime(cwd, {});
// after
const candidates = enumeratePythonRuntimes(cwd, baseEnv);
if (candidates.length === 0) throw new Error("Install python3 or set PY_BIN");
const runtime = candidates[0];

import { enumeratePythonRuntimes } from "...";
const candidates = enumeratePythonRuntimes(cwd, baseEnv);
if (candidates.length === 0) {
  // surface install guidance before calling resolvePythonRuntime
}

let runtime;
try {
  runtime = resolvePythonRuntime(cwd, baseEnv);
} catch (e) {
  if (e instanceof Error && e.message.includes("Python executable not found")) {
    throw new Error("Install Python 3 and ensure it is on PATH");
  }
  throw e;
}

When it happens

Trigger: Starting the Python eval runtime on a machine with no python/python3 (or venv) discoverable via the candidate enumeration in cwd or baseEnv PATH — e.g. resolvePythonRuntime(cwd, env) in a slim Docker image or minimal CI runner.

Common situations: Alpine/slim containers without python installed, Windows machines with Python installed but python.exe not on PATH, broken virtualenv references (venv python deleted), or a sanitized env stripping PATH.

Related errors

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