apache/beam · error · TypeCheckError

The transform ' ' requires PCollections of type ' ' but was…

Error message

The transform '{label}' requires PCollections of type '{element_hint}' but was applied to a PCollection of type '{bindings[element_arg]}' (produced by the transform '{producer_label}').

What it means

During pipeline type checking, Beam verifies that the PCollection fed into a transform has an element type consistent with the transform's declared element type hint (`element_arg`). If the producer's declared type is inconsistent, a TypeCheckError is raised naming the expected type, the actual type, and the upstream transform that produced the PCollection.

Solutions

Read the producer transform named in the message and fix its output type or `with_output_types` hint so it matches what the consumer expects.
Update the consumer's declared element hint (`with_input_types`/typed DoFn `process` signature) to match the real data.
Insert an explicit conversion map (`beam.Map(convert_fn).with_output_types(T)`) between producer and consumer.
As a last resort, disable checking (`--type_check_strictness=ALL_REQUIRED` off / `--no_type_check`), but this hides real bugs.

Example fix

# before
pc = (p | beam.Create(['1','2']) | beam.Map(int) | beam.Map(lambda x: x + 'x'))
# after
pc = (p | beam.Create(['1','2']) | beam.Map(lambda x: str(int(x)) + 'x'))

Defensive patterns

Strategy: validation

Validate before calling

from apache_beam import typehints
assert typehints.is_consistent_with(producer_out_type, expected_element_type), \
  f'producer yields {producer_out_type}, transform needs {expected_element_type}'

Type guard

def matches_element_hint(pcoll, hint):
  from apache_beam import typehints
  return typehints.is_consistent_with(pcoll.element_type, hint)

Try / catch

try:
  out = pc | 'step' >> MyTypedTransform()
except TypeCheckError as e:
  log.error('Type mismatch in pipeline: %s', e)
  raise

Prevention

Annotate every transform with with_output_types/with_input_types so mismatches surface at the producing stage.
Run pipelines with type checking enabled locally before submitting to the runner.
Keep hints updated whenever an element type changes during refactoring.

When it happens

Trigger: Applying a transform (e.g. one with `with_input_types` or a GroupByKey-ish element hint) to a PCollection whose runtime type hint from the producing transform doesn't match, while pipeline type checking is enabled (default; disabled via --type_check_strictness or --no_type_check).

Common situations: Chaining transforms where an earlier map changed the element type without updating hints; mixing typed and untyped PCollections; copy-pasted pipeline fragments where a source transform's output type changed after a library upgrade.

Understand the failure class

Background: Type mismatch errors: IllegalArgumentException, TypeError and type guards across 150 open-source libraries — this error's family across 150 libraries.

Related errors

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

Appendix: source

Thrown at sdks/python/apache_beam/transforms/ptransform.py:990

        return instance_to_type(side_input)

      arg_types = [pvalueish.element_type] + [element_type(v) for v in args]
      kwargs_types = {k: element_type(v) for (k, v) in kwargs.items()}
      argspec_fn = self._process_argspec_fn()
      bindings = getcallargs_forhints(argspec_fn, *arg_types, **kwargs_types)
      hints = getcallargs_forhints(
          argspec_fn, *input_types[0], **input_types[1])

      # First check the main input.
      arg_hints = iter(hints.items())
      element_arg, element_hint = next(arg_hints)
      if not typehints.is_consistent_with(
          bindings.get(element_arg, typehints.Any), element_hint):
        transform_nest_level = self.label.count("/")
        split_producer_label = pvalueish.producer.full_label.split("/")
        producer_label = "/".join(
            split_producer_label[:transform_nest_level + 1])
        raise TypeCheckError(
            f"The transform '{self.label}' requires "
            f"PCollections of type '{element_hint}' "
            f"but was applied to a PCollection of type"
            f" '{bindings[element_arg]}' "
            f"(produced by the transform '{producer_label}'). ")

      # Now check the side inputs.
      for arg, hint in arg_hints:
        if arg.startswith('__unknown__'):
          continue
        if hint is None:
          continue
        if not typehints.is_consistent_with(bindings.get(arg, typehints.Any),
                                            hint):
          raise TypeCheckError(
              'Type hint violation for \'{label}\': requires {hint} but got '
              '{actual_type} for {arg}\nFull type hint:\n{debug_str}'.format(
                  label=self.label,

View on GitHub (pinned to 12126d8942)