{"record":{"id":"00f6c4805f40ffd9","repo":"apache/beam","slug":"can-t-find-a-python-executable","errorCode":null,"errorMessage":"Can't find a Python executable.","messagePattern":"Can't find a Python executable\\.","errorType":"exception","errorClass":"Error","httpStatus":null,"severity":"error","filePath":"sdks/typescript/src/apache_beam/utils/service.ts","lineNumber":400,"sourceCode":"    );\n  }\n}\n\nexport class PythonService extends SubprocessService {\n  static VENV_CACHE = path.join(BEAM_CACHE, \"venvs\");\n\n  static whichPython(): string {\n    for (const bin of [\"python3\", \"python\"]) {\n      try {\n        const result = childProcess.spawnSync(bin, [\"--version\"]);\n        if (result.status === 0) {\n          return bin;\n        }\n      } catch (err) {\n        // Try the next one.\n      }\n    }\n    throw new Error(\"Can't find a Python executable.\");\n  }\n\n  static beamPython(): string {\n    const bootstrapScript = path.join(\n      __dirname,\n      \"..\",\n      \"..\",\n      \"..\",\n      \"resources\",\n      \"bootstrap_beam_venv.py\",\n    );\n    console.debug(\"Invoking Python bootstrap script.\");\n    const result = childProcess.spawnSync(\n      PythonService.whichPython(),\n      [bootstrapScript],\n      { encoding: \"latin1\" },\n    );\n    if (result.status === 0) {","sourceCodeStart":382,"sourceCodeEnd":418,"githubUrl":"https://github.com/apache/beam/blob/12126d8942aaf848030c478b4c6a28c6af861c66/sdks/typescript/src/apache_beam/utils/service.ts#L382-L418","documentation":"whichPython probes a list of candidate Python executables (via version checks) and throws if none can be found or executed. The TypeScript SDK needs a Python interpreter to launch Python-side services (e.g. the expansion service); without one, start() cannot proceed.","triggerScenarios":"Calling start() on a service requiring Python when neither `python3`/`python` nor any configured candidate resolves to a working executable.","commonSituations":"Python not installed or not on PATH in the container/CI image; using a name like `python3.11` that isn't installed; PATH differs in the Node process's environment; broken Python installation that fails the version check.","solutions":["Install Python 3 and ensure it is on PATH for the process running the pipeline.","Set an environment variable / service option pointing to a specific Python binary if the SDK supports configuring it (e.g. via whichPython candidates or options).","Verify by running `which python3; python3 --version` in the same environment.","Fix broken symlinks/aliases (e.g. `python` missing on Debian/Ubuntu without python-is-python3)."],"exampleFix":"// before: fails in minimal container\nawait start();\n\n// after: ensure interpreter is available\n// Dockerfile: RUN apt-get update && apt-get install -y python3\nprocess.env.PATH = \"/usr/local/bin:\" + process.env.PATH;\nawait start();","handlingStrategy":"fallback","validationCode":"import {execSync} from 'child_process';\nfunction pythonAvailable(bin: string): boolean {\n  try { execSync(`${bin} --version`, {stdio: 'ignore'}); return true; }\n  catch { return false; }\n}","typeGuard":null,"tryCatchPattern":"try {\n  await service.start();\n} catch (e) {\n  if (/Can't find a Python executable/.test(String(e))) {\n    throw new Error('Install Python 3 or add it to PATH before running this pipeline');\n  }\n  throw e;\n}","preventionTips":["Install Python 3 in all environments that run the pipeline (including containers).","Verify PATH inside the Node process, not just the interactive shell.","Provide a python-is-python3 alias or explicit interpreter configuration."],"tags":["python","environment","missing-dependency","service-startup"],"backgroundTag":"command-not-found","analyzedSha":"12126d8942aaf848030c478b4c6a28c6af861c66","analyzedAt":"2026-09-13T01:50:10.254Z","contentChangedAt":"2026-09-13T01:50:10.254Z","schemaVersion":2},"datasetVersion":"2026-09-15T13:17:12.816Z"}