{"record":{"id":"de308a0fbb54b012","repo":"can1357/oh-my-pi","slug":"python-kernel-unavailable","errorCode":null,"errorMessage":"Python kernel unavailable","messagePattern":"Python kernel unavailable","errorType":"exception","errorClass":"Error","httpStatus":null,"severity":"error","filePath":"packages/coding-agent/src/eval/py/executor.ts","lineNumber":337,"sourceCode":"\t\tcode,\n\t\toptions,\n\t\trunIdPrefix: \"py\",\n\t\terrorLogLabel: \"Python\",\n\t\tcancelledErrorClass: PythonExecutionCancelledError,\n\t\tbuildKernelEnvPatch: buildManagedKernelEnvPatch,\n\t\tformatKernelTimeoutAnnotation,\n\t\tformatTimeoutAnnotation,\n\t});\n}\n\nasync function ensureKernelAvailable(cwd: string, options: PythonExecutorOptions): Promise<void> {\n\tconst availability = await waitForPromiseWithCancellation(\n\t\tcheckPythonKernelAvailability(cwd, options.interpreter),\n\t\toptions,\n\t\tPythonExecutionCancelledError,\n\t);\n\tif (!availability.ok) {\n\t\tthrow new Error(availability.reason ?? \"Python kernel unavailable\");\n\t}\n}\n\nasync function ensureToolBridge(options: PythonExecutorOptions): Promise<void> {\n\tif (!options.toolSession || options.bridge) return;\n\ttry {\n\t\toptions.bridge = await ensurePyToolBridge();\n\t} catch (err) {\n\t\tlogger.warn(\"Failed to start Python tool bridge\", {\n\t\t\terror: err instanceof Error ? err.message : String(err),\n\t\t});\n\t}\n}\n\nasync function executePerCall(code: string, cwd: string, options: PythonExecutorOptions): Promise<PythonResult> {\n\tif (options.bridge && !options.bridgeSessionId) {\n\t\toptions.bridgeSessionId = `py-bridge:${crypto.randomUUID()}`;\n\t}","sourceCodeStart":319,"sourceCodeEnd":355,"githubUrl":"https://github.com/can1357/oh-my-pi/blob/969062200754ea02cfac922e5ebb8c608c079e15/packages/coding-agent/src/eval/py/executor.ts#L319-L355","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","solutions":["Install Python or fix PATH so `python`/`python3` resolves in the executor's shell environment.","Pass options.interpreter with an absolute path to a working interpreter (e.g. .venv/bin/python).","Recreate the virtualenv if its python binary is missing/broken.","Read availability.reason in the thrown message — it names the concrete failure (e.g. 'Python executable not found on PATH')."],"exampleFix":"// before\nawait executePython(cwd, code); // relies on PATH\n// after\nawait executePython(cwd, code, { interpreter: \"/path/to/project/.venv/bin/python\" });","handlingStrategy":"validation","validationCode":"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');","typeGuard":"function isKernelUnavailable(e: unknown): e is Error { return e instanceof Error && /Python kernel unavailable|not found on PATH/.test(e.message); }","tryCatchPattern":"try {\n  await ensureKernelAvailable(options);\n} catch (err) {\n  if (err instanceof Error && err.message.startsWith('Python kernel unavailable')) {\n    // fall back to an explicit interpreter or fail the run with a setup hint\n  } else throw err;\n}","preventionTips":["Pin an absolute interpreter path in options.interpreter for CI/containers.","Smoke-test `python -c \"import sys\"` in your environment setup step.","Recreate venvs after deleting site-packages; don't leave dangling .venv paths.","Remember availability success is cached per cwd+interpreter; failures re-probe, so fixes apply immediately."],"tags":["python","environment","interpreter","path"],"backgroundTag":"python-not-found","analyzedSha":"969062200754ea02cfac922e5ebb8c608c079e15","analyzedAt":"2026-08-31T10:29:35.737Z","schemaVersion":2},"datasetVersion":"2026-08-31T14:17:45.589Z"}