apache/beam · error · ValueError

Cannot start an expansion service since neither Java nor…

Error message

Cannot start an expansion service since neither Java nor Docker executables are available in the system.

What it means

Beam attempted to auto-start a Docker-Compose-based transform service because no Java expansion service was provided, but neither a Java nor a Docker executable exists on the machine, so no service can be launched and expansion falls through to this final error.

Solutions

  1. Install a JRE/JDK (java on PATH) so the expansion service jar can run
  2. Or install Docker so the containerized transform service can be used
  3. Or run a remote expansion service and pass its endpoint explicitly
Defensive patterns

Strategy: fallback

When it happens

Trigger: Thrown at sdks/python/apache_beam/transforms/external.py:1262 when the library encounters an invalid state.

Common situations: See trigger scenarios.

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

Appendix: source

Thrown at sdks/python/apache_beam/transforms/external.py:1262

    else:
      error_append = 'a Java expansion service was not provided.'

    project_name = str(uuid.uuid4())
    port = subprocess_server.pick_port(None)[0]

    logging.info(
        'Trying to expand the external transform using the Docker Compose '
        'based transform service since %s. Transform service will be under '
        'Docker Compose project name %s and will be made available at port %r.'
        % (error_append, project_name, str(port)))

    from apache_beam import version as beam_version
    beam_version = beam_version.__version__

    return transform_service_launcher.TransformServiceLauncher(
        project_name, port, beam_version, user_agent)
  else:
    raise ValueError(
        'Cannot start an expansion service since neither Java nor '
        'Docker executables are available in the system.')


def _sanitize_java_traceback(s):
  """Attempts to highlight the root cause in the error string.

  Java tracebacks read bottom to top, while Python tracebacks read top to
  bottom, resulting in the actual error message getting sandwiched between two
  walls of text.  This may result in the error being duplicated (as we don't
  want to remove relevant information) but should be clearer in most cases.

  Best-effort but non-destructive.
  """
  # We delete non-java-traceback lines.
  traceback_lines = [
      r'\tat \S+\(\S+\.java:\d+\)',
      r'\t\.\.\. \d+ more',

View on GitHub (pinned to 12126d8942)