apache/beam · error · ValueError

f'Unknown output at line : only has outputs

Error message

f'Unknown output {repr(output)} at line {SafeLineLoader.get_line(name)}: {transform} only has outputs {list(outputs.keys())}'

What it means

Scope.get_pcollection resolves a reference of the form `TransformName.output` to a PCollection. When the named output tag does not exist on the transform's outputs (and the transform does not have exactly one output), Beam raises this ValueError listing the outputs the transform actually produces.

Solutions

Correct the output tag after the dot to one of the outputs listed in the error.
Compare the reference against the transform's actual output tags.
If the transform has only one output, drop the `.tag` suffix and reference the transform name alone.
If you expected an error output, add `error_handling: {output: ...}` config to the producing transform.

Example fix

# before
input: LogRows.missing_collumn
# after
input: LogRows.missing_column

Defensive patterns

Strategy: validation

Validate before calling

tags = {'main', 'errors'}  # outputs the transform actually declares
ref, _, tag = input_ref.partition('.')
if tag and tag not in tags:
    raise ValueError(f'{ref} has no output {tag}; known: {tags}')

Type guard

def output_exists(transform_spec, tag):
    known = set(transform_spec.get('outputs', {}).keys()) | {'main'}
    return tag in known

Try / catch

try:
    pcoll = scope.get_pcollection(name)
except ValueError as e:
    if 'Unknown output' in str(e):
        raise UserPipelineError(f'Fix reference {name}; available outputs are listed in the message') from e

Prevention

Reference single-output transforms without a .tag suffix
Keep output tag names in sync when refactoring transforms
Check error_handling.output config when consuming error outputs

When it happens

Trigger: Writing an input reference like `MyTransform.bad_rows` where `MyTransform` has no output tagged `bad_rows`; referencing an output of a single-output transform with a tag it does not use; typos in the output tag after the dot.

Common situations: Typos in dotted references; upstream transform renamed its output tags; referencing an error-handling output that was never configured; copy-pasting references between pipelines.

Understand the failure class

Background: 'Could not be found', 'does not exist', 'not found in database': the resource-not-found family when an ID, slug, key, or URI lookup comes back empty — this error's family across 20 libraries.

Related errors

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

Appendix: source

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

              self._all_followers[transform_id].append(transform['__uuid__'])
    return self._all_followers[self.get_transform_id(transform_name)]

  def compute_all(self):
    for transform_id in self._transforms_by_uuid.keys():
      self.compute_outputs(transform_id)

  def get_pcollection(self, name):
    if name in self._inputs:
      return self._inputs[name]
    elif '.' in name:
      transform, output = name.rsplit('.', 1)
      outputs = self.get_outputs(transform)
      if output in outputs:
        return outputs[output]
      elif len(outputs) == 1 and outputs[next(iter(outputs))].tag == output:
        return outputs[next(iter(outputs))]
      else:
        raise ValueError(
            f'Unknown output {repr(output)} '
            f'at line {SafeLineLoader.get_line(name)}: '
            f'{transform} only has outputs {list(outputs.keys())}')
    else:
      outputs = self.get_outputs(name)
      if len(outputs) == 1:
        return only_element(outputs.values())
      else:
        error_output = self._transforms_by_uuid[self.get_transform_id(
            name)]['config'].get('error_handling', {}).get('output')
        if error_output and error_output in outputs and len(outputs) == 2:
          return next(
              output for tag, output in outputs.items() if tag != error_output)
        raise ValueError(
            f'Ambiguous output at line {SafeLineLoader.get_line(name)}: '
            f'{name} has outputs {list(outputs.keys())}')

  def get_outputs(self, transform_name):

View on GitHub (pinned to 12126d8942)