apache/beam · error · ValueError

f'Unknown transform at line

Error message

f'Unknown transform at line {SafeLineLoader.get_line(transform_name)}: {transform_name}'

What it means

Raised by Scope.get_transform_id when resolving a name reference in a YAML pipeline: the name is neither a raw UUID nor present in the name-to-UUID index built from transform specs. Because SafeLineLoader tracks YAML line numbers, the message pinpoints the line of the offending reference. The input at fault is a misspelled or dangling reference to a transform name (or type) in inputs/outputs or another reference field.

Solutions

  1. Fix the referenced name to match an existing transform's 'name' or 'type' in the pipeline spec
  2. Define the referenced transform or remove the dangling reference
  3. Check the reported YAML line for typos, quoting, or wrong indentation
Defensive patterns

Strategy: validation

When it happens

Trigger: Thrown at sdks/python/apache_beam/yaml/yaml_transform.py:164 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/b1e2e792349fe9d2. Report an issue: GitHub.

Appendix: source

Thrown at sdks/python/apache_beam/yaml/yaml_transform.py:164

      if 'name' in spec:
        self._uuid_by_name[spec['name']].add(spec['__uuid__'])
      if 'type' in spec:
        self._uuid_by_name[spec['type']].add(spec['__uuid__'])

  def get_transform_id_and_output_name(self, name):
    if '.' in name:
      transform_name, output = name.rsplit('.', 1)
    else:
      transform_name, output = name, None
    return self.get_transform_id(transform_name), output

  def get_transform_id(self, transform_name):
    if transform_name in self._transforms_by_uuid:
      return transform_name
    else:
      candidates = self._uuid_by_name[transform_name]
      if not candidates:
        raise ValueError(
            f'Unknown transform at line '
            f'{SafeLineLoader.get_line(transform_name)}: {transform_name}')
      elif len(candidates) > 1:
        raise ValueError(
            f'Ambiguous transform at line '
            f'{SafeLineLoader.get_line(transform_name)}: {transform_name}')
      else:
        return only_element(candidates)

  def get_transform_spec(self, transform_name_or_id):
    return self._transforms_by_uuid[self.get_transform_id(transform_name_or_id)]


class Scope(LightweightScope):
  """To look up PCollections (typically outputs of prior transforms) by name."""
  def __init__(
      self,
      root,

View on GitHub (pinned to 12126d8942)