apache/beam · critical · RuntimeException

Python bootstrap failed with error ${result}, ${lastNonEmpty

Error message

Python bootstrap failed with error ${result}, ${lastNonEmptyLine}

What it means

PythonService.start first runs the Python bootstrap script to locate the interpreter and provision the environment. If that bootstrap process exits with a non-zero code, the library throws RuntimeException including the exit code and the last non-empty output line, which usually contains the underlying pip/python error.

Solutions

Read the lastNonEmptyLine in the exception message — it contains the actual bootstrap error and fix that first
Run the bootstrap manually (python -m pip install 'apache_beam[...]==<version>') to reproduce and fix the environment
Verify a supported Python 3 interpreter is on PATH and pip works (python --version, pip download test)
Check network/proxy settings if PyPI is unreachable

Example fix

// before (shell)
export PATH=/usr/bin:$PATH   # picks python2
// after
export PATH=/usr/local/bin:$PATH  # python3.x first; or set
PythonService.setPythonExecutable("/usr/bin/python3.9");

Defensive patterns

Strategy: try-catch

Validate before calling

Process p = new ProcessBuilder("python3", "--version").start();
if (p.waitFor() != 0) { throw new IllegalStateException("python3 not usable"); }

Try / catch

try {
  service.start();
} catch (RuntimeException e) {
  if (e.getMessage().startsWith("Python bootstrap failed")) {
    // inspect embedded error line; fix env (pip/python version/network) and retry
  }
}

Prevention

Pin a supported Python 3 interpreter via PythonService.setPythonExecutable
Ensure pip and network access to PyPI in CI/containers
Run bootstrap once at deploy time and cache the prepared environment
Check the exception's embedded lastNonEmptyLine for the root cause

When it happens

Trigger: Bootstrap subprocess exits non-zero: broken python installation, missing pip/setuptools, network failure downloading the beam Apache Beam package, incompatible Python version, or a corrupted virtualenv created during bootstrapping.

Common situations: No internet access in CI so pip install fails; Python 2.7 found instead of a supported Python 3; proxy/firewall blocking PyPI; --bootstrap with a bad requirements spec.

Related errors

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

Appendix: source

Thrown at sdks/java/extensions/python/src/main/java/org/apache/beam/sdk/extensions/python/PythonService.java:123

    Process bootstrap =
        new ProcessBuilder(bootstrapCommand).redirectError(ProcessBuilder.Redirect.INHERIT).start();
    bootstrap.getOutputStream().close();
    BufferedReader reader =
        new BufferedReader(
            new InputStreamReader(bootstrap.getInputStream(), StandardCharsets.UTF_8));
    String lastLine = reader.readLine();
    String lastNonEmptyLine = lastLine;
    while (lastLine != null) {
      LOG.info("{}", lastLine);
      if (lastLine.length() > 0) {
        lastNonEmptyLine = lastLine;
      }
      lastLine = reader.readLine();
    }
    reader.close(); // Make SpotBugs happy.
    int result = bootstrap.waitFor();
    if (result != 0) {
      throw new RuntimeException(
          "Python bootstrap failed with error " + result + ", " + lastNonEmptyLine);
    }
    String pythonExecutable = lastNonEmptyLine;
    List<String> command = new ArrayList<>();
    command.add(pythonExecutable);
    command.add("-m");
    command.add(module);
    command.addAll(args);
    LOG.info("Starting python service with arguments {}", command);
    Process p =
        new ProcessBuilder(command)
            .redirectError(ProcessBuilder.Redirect.INHERIT)
            .redirectOutput(ProcessBuilder.Redirect.INHERIT)
            .start();
    return p::destroy;
  }

  private String whichPython() {

View on GitHub (pinned to 12126d8942)