apache/beam · error · Error

Can't find a Python executable.

Error message

Can't find a Python executable.

What it means

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.

Source

Thrown at sdks/typescript/src/apache_beam/utils/service.ts:400

    );
  }
}

export class PythonService extends SubprocessService {
  static VENV_CACHE = path.join(BEAM_CACHE, "venvs");

  static whichPython(): string {
    for (const bin of ["python3", "python"]) {
      try {
        const result = childProcess.spawnSync(bin, ["--version"]);
        if (result.status === 0) {
          return bin;
        }
      } catch (err) {
        // Try the next one.
      }
    }
    throw new Error("Can't find a Python executable.");
  }

  static beamPython(): string {
    const bootstrapScript = path.join(
      __dirname,
      "..",
      "..",
      "..",
      "resources",
      "bootstrap_beam_venv.py",
    );
    console.debug("Invoking Python bootstrap script.");
    const result = childProcess.spawnSync(
      PythonService.whichPython(),
      [bootstrapScript],
      { encoding: "latin1" },
    );
    if (result.status === 0) {

View on GitHub (pinned to 12126d8942)

Solutions

1. Install Python 3 and ensure it is on PATH for the process running the pipeline.
2. 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).
3. Verify by running `which python3; python3 --version` in the same environment.
4. Fix broken symlinks/aliases (e.g. `python` missing on Debian/Ubuntu without python-is-python3).

Example fix

// before: fails in minimal container
await start();

// after: ensure interpreter is available
// Dockerfile: RUN apt-get update && apt-get install -y python3
process.env.PATH = "/usr/local/bin:" + process.env.PATH;
await start();

import {execSync} from 'child_process';
function pythonAvailable(bin: string): boolean {
  try { execSync(`${bin} --version`, {stdio: 'ignore'}); return true; }
  catch { return false; }
}

try {
  await service.start();
} catch (e) {
  if (/Can't find a Python executable/.test(String(e))) {
    throw new Error('Install Python 3 or add it to PATH before running this pipeline');
  }
  throw e;
}

When it happens

Trigger: Calling start() on a service requiring Python when neither `python3`/`python` nor any configured candidate resolves to a working executable.

Common situations: 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.

Related errors

• Java must be installed on this system to use this transform/
• No proto encoding for PaneInfoCoder, always part of Windowed
• Python bootstrap failed with error ${result}, ${lastNonEmpty
• Unable to find a suitable Python executable.
• This pipeline contains a DillCoder which requires the dill p

AI-assisted analysis of apache/beam@12126d8942 (2026-09-13). Data as JSON: /api/errors/00f6c4805f40ffd9. Report an issue: GitHub.