apache/beam · error · RuntimeError

Java must be installed on this system to use this transform/

Error message

Java must be installed on this system to use this transform/runner.

What it means

Sibling of the JAVA_HOME error: start_process() raises this when shutil.which(java_path) finds no java executable at all — no usable JAVA_HOME and no java on PATH. Beam's Python pipeline needs Java installed to run Java-backed transforms/runner services.

Source

Thrown at sdks/python/apache_beam/utils/subprocess_server.py:389

        stub_class,
        [self._java_path, '-jar', path_to_jar] + list(java_arguments),
        logger=logger)
    self._existing_service = path_to_jar if is_service_endpoint(
        path_to_jar) else None

  def start_process(self):
    if self._existing_service:
      return None, self._existing_service
    else:
      if not shutil.which(self._java_path):
        java_home = os.environ.get('JAVA_HOME')
        if java_home:
          raise RuntimeError(
              'Java is not correctly installed in JAVA_HOME=%s to use this '
              'transform/runner. Please check if JAVA_HOME is correctly set and'
              ' points to your Java installation directory.' % java_home)
        else:
          raise RuntimeError(
              'Java must be installed on this system to use this '
              'transform/runner.')
      return super().start_process()

  def stop_process(self):
    if self._existing_service:
      pass
    else:
      return super().stop_process()

  @classmethod
  def jar_name(cls, artifact_id, version, classifier=None, appendix=None):
    return '-'.join(
        filter(None, [artifact_id, appendix, version, classifier])) + '.jar'

  @classmethod
  def path_to_maven_jar(
      cls,

View on GitHub (pinned to 12126d8942)

Solutions

Install a JDK (e.g. apt-get install openjdk-17-jdk or brew install openjdk@17).
Ensure java is on PATH: verify 'which java' returns a path.
Or set JAVA_HOME to an existing JDK root directory.
In CI, add a Java setup step (e.g. actions/setup-java) before running the pipeline.

Example fix

// before
# no java installed
python -m apache_beam.runners.portability... 
// after
sudo apt-get install -y openjdk-17-jdk
export JAVA_HOME=$(dirname $(dirname $(readlink -f $(which java))))

Defensive patterns

Strategy: validation

Validate before calling

import shutil
if not shutil.which('java'):
    raise SystemExit('Java is required: install a JDK and/or set JAVA_HOME')

Prevention

Add a JDK to base/CI images used for Beam
Run 'which java' as a preflight check
Document Java requirement for Java-backed runners
Use setup-java in CI workflows

When it happens

Trigger: Invoking Java-dependent functionality (FlinkRunner, SparkRunner, expansion/beam services) on a machine with no JDK installed and no java binary discoverable via JAVA_HOME or PATH.

Common situations: Fresh containers/CI images (e.g. python:slim) without a JDK; developers testing Dataflow/Samza/Flink pipelines locally with only Python installed.

Understand the failure class

Background: "not installed", "pip install", "required for": how missing-dependency errors surface across open-source libraries — this error's family across 34 libraries.

Related errors

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