apache/beam · error · ValueError

No expansion service was specified and could not find a…

Error message

No expansion service was specified and could not find a default expansion service for %s: '%s'.

What it means

Managed transforms run via a Java expansion service. If the user did not pass an expansion_service and no default JAR target exists for the transform identifier, this ValueError is raised because Beam cannot start a service to expand the transform.

Solutions

Pass an explicit expansion_service argument pointing to your running expansion service address.
Upgrade apache_beam so a default expansion service jar target exists for the transform.
Verify MANAGED_TRANSFORM_URN_TO_JAR_TARGET_MAPPING includes your transform's identifier.

Example fix

// before
beam.managed.Write('iceberg')
// after
beam.managed.Write('iceberg', expansion_service='localhost:8099')

Defensive patterns

Strategy: validation

Validate before calling

from apache_beam.transforms.managed import MANAGED_TRANSFORM_URN_TO_JAR_TARGET_MAPPING
identifier = Write._WRITE_TRANSFORMS.get(sink.lower())
assert identifier in MANAGED_TRANSFORM_URN_TO_JAR_TARGET_MAPPING or expansion_service, "need expansion_service"

Prevention

Always provide expansion_service in environments without default jar access
Pin a Beam version known to support your managed transform

When it happens

Trigger: Running a managed transform (e.g. Read/Write) whose identifier is missing from MANAGED_TRANSFORM_URN_TO_JAR_TARGET_MAPPING while expansion_service=None, typically on an old Beam version or a custom transform.

Common situations: Using a Beam version where the requested managed transform has no prebuilt expansion service jar; custom expansion environments without the default Maven repository; running with a pipeline option misconfiguration.

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/43af2c5fc608f438. Report an issue: GitHub.

Appendix: source

Thrown at sdks/python/apache_beam/transforms/managed.py:214

        config_url=self._config_url)

  def default_label(self) -> str:
    return "Managed Write(%s)" % self._sink.upper()


def _resolve_expansion_service(
    transform_name: str,
    identifier: str,
    expansion_service,
    pipeline_options=None):
  if expansion_service:
    return expansion_service

  gradle_target = None
  if identifier in MANAGED_TRANSFORM_URN_TO_JAR_TARGET_MAPPING:
    gradle_target = MANAGED_TRANSFORM_URN_TO_JAR_TARGET_MAPPING.get(identifier)
  if not gradle_target:
    raise ValueError(
        "No expansion service was specified and could not find a "
        f"default expansion service for {transform_name}: '{identifier}'.")

  # Extract maven_repository_url and user_agent from pipeline options if
  # available
  maven_repository_url = None
  user_agent = None
  if pipeline_options:
    from apache_beam.options import pipeline_options as po
    setup_options = pipeline_options.view_as(po.SetupOptions)
    maven_repository_url = setup_options.maven_repository_url
    user_agent = setup_options.user_agent

  return BeamJarExpansionService(
      gradle_target,
      maven_repository_url=maven_repository_url,
      user_agent=user_agent)

View on GitHub (pinned to 12126d8942)