{"record":{"id":"548bc5c3dd9a017b","repo":"can1357/oh-my-pi","slug":"python-kernel-unavailable-548bc5","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/kernel.ts","lineNumber":151,"sourceCode":"\t\t\t\t\tid: msgId,\n\t\t\t\t\tcode,\n\t\t\t\t\tcwd: opts?.cwd,\n\t\t\t\t\tenv: opts?.env,\n\t\t\t\t\tsilent: opts?.silent ?? false,\n\t\t\t\t\tstoreHistory: opts?.storeHistory ?? !(opts?.silent ?? false),\n\t\t\t\t}),\n\t\t});\n\t}\n\n\tstatic async start(options: KernelStartOptions): Promise<PythonKernel> {\n\t\tconst availability = await logger.time(\n\t\t\t\"PythonKernel.start:availabilityCheck\",\n\t\t\tcheckPythonKernelAvailability,\n\t\t\toptions.cwd,\n\t\t\toptions.interpreter,\n\t\t);\n\t\tif (!availability.ok) {\n\t\t\tthrow new Error(availability.reason ?? \"Python kernel unavailable\");\n\t\t}\n\n\t\tlet runtime = availability.runtime;\n\t\tif (!runtime) {\n\t\t\tconst { env: shellEnv } = (await Settings.init()).getShellConfig();\n\t\t\truntime = options.interpreter\n\t\t\t\t? resolveExplicitPythonRuntime(options.interpreter, options.cwd, filterEnv(shellEnv))\n\t\t\t\t: resolvePythonRuntime(options.cwd, filterEnv(shellEnv));\n\t\t}\n\t\tconst spawnEnv: Record<string, string> = {};\n\t\tfor (const [key, value] of Object.entries(runtime.env)) {\n\t\t\tif (typeof value === \"string\") spawnEnv[key] = value;\n\t\t}\n\t\tfor (const [key, value] of Object.entries(options.env ?? {})) {\n\t\t\tif (typeof value === \"string\") spawnEnv[key] = value;\n\t\t}\n\t\tspawnEnv.PYTHONUNBUFFERED = \"1\";\n\t\tspawnEnv.PYTHONIOENCODING = \"utf-8\";","sourceCodeStart":133,"sourceCodeEnd":169,"githubUrl":"https://github.com/can1357/oh-my-pi/blob/969062200754ea02cfac922e5ebb8c608c079e15/packages/coding-agent/src/eval/py/kernel.ts#L133-L169","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","solutions":["Install Python or correct PATH in the shell environment used by the settings' shell config.","Pass an explicit, existing interpreter path via options.interpreter.","If the reason is a cancelled probe, retry with a longer probe timeout / without an aborting signal.","Failures aren't cached — fixing the environment is picked up on the next start attempt."],"exampleFix":"// before\nconst kernel = new PythonKernel({ cwd, interpreter: \"python3.13\" }); // not installed\nawait kernel.start();\n// after\nconst kernel = new PythonKernel({ cwd, interpreter: \"/usr/bin/python3\" }); // exists\nawait kernel.start();","handlingStrategy":"validation","validationCode":"const probe = Bun.spawnSync([interpreter ?? \"python3\", \"--version\"]); if (!probe.success) throw new Error(`Interpreter ${interpreter ?? 'python3'} is not runnable`);","typeGuard":"function isKernelStartError(e: unknown): e is Error { return e instanceof Error && e.message.includes('Python kernel unavailable'); }","tryCatchPattern":"try {\n  await kernel.start();\n} catch (err) {\n  if (err instanceof Error && err.message.includes('Python kernel unavailable')) {\n    // inspect err.message for the concrete probe reason and fix the environment\n  } else throw err;\n}","preventionTips":["Verify the interpreter exists and is executable before constructing PythonKernel.","Use absolute interpreter paths; avoid pyenv shims in headless environments.","Ensure the shell config's PATH (Settings.getShellConfig) includes Python in non-interactive runs.","Give the availability probe a generous timeoutMs on slow machines."],"tags":["python","environment","interpreter","kernel"],"backgroundTag":"python-not-found","analyzedSha":"969062200754ea02cfac922e5ebb8c608c079e15","analyzedAt":"2026-08-31T10:29:35.737Z","schemaVersion":2},"datasetVersion":"2026-08-31T14:17:45.589Z"}