apache/beam · error · RuntimeError

Java is not correctly installed in JAVA_HOME=%s to use this

Error message

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.

What it means

JavaJarServer.start_process() checks that the java executable (java_path, typically from JAVA_HOME) exists via shutil.which before spawning the job server. If which() fails but JAVA_HOME is set, it raises this error telling you JAVA_HOME does not point to a valid Java installation.

Source

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

    if classpath:
      # java -jar ignores the classpath, so we make a new jar that embeds
      # the requested classpath.
      path_to_jar = self.make_classpath_jar(path_to_jar, classpath, cache_dir)
    super().__init__(
        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(

View on GitHub (pinned to 12126d8942)

Solutions

1. Verify $JAVA_HOME/bin/java exists and runs: run '$JAVA_HOME/bin/java -version'.
2. Correct JAVA_HOME in your shell/profile to the real JDK root (e.g. /usr/lib/jvm/java-17-openjdk-amd64).
3. Install a full JDK (not just JRE) at the JAVA_HOME path.
4. Unset JAVA_HOME so Beam falls back to java on PATH, if PATH has a valid java.

Example fix

// before
export JAVA_HOME=/usr/lib/jvm/java  # directory does not contain bin/java
// after
export JAVA_HOME=/usr/lib/jvm/java-17-openjdk-amd64
export PATH=$JAVA_HOME/bin:$PATH

import os, shutil
jh = os.environ.get('JAVA_HOME')
if jh and not shutil.which(os.path.join(jh, 'bin', 'java')):
    raise SystemExit(f'JAVA_HOME={jh} has no bin/java; fix before starting')

When it happens

Trigger: Calling any runner/transform that launches a Java subprocess (FlinkRunner, SparkRunner, expansion service, job server) while JAVA_HOME is set but $JAVA_HOME/bin/java does not exist or is not executable.

Common situations: JAVA_HOME pointing to a JRE-only directory, a deleted/upgraded JDK path, a typo like /usr/lib/jvm/java (missing version), or an exploded/unpacked JDK missing bin/java; docker images where JAVA_HOME env var was set but the JDK was removed.

Understand the failure class

Background: "environment variable is not set" and "Missing keys in environment" errors: what missing required env var messages mean and how to fix them — this error's family across 28 libraries.

Related errors

• No proto encoding for PaneInfoCoder, always part of Windowed
• Java must be installed on this system to use this transform/
• Timing number 0b" + timingNumber.toString(2) + " has more th
• No filesystem found for scheme
• Exploded field %s must be an iterable type, got %s.

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