apache/beam · error · TypeCheckError

Type hint violation for

Error message

Type hint violation for '{label}': requires {hint} but got {actual_type} for {arg}
Full type hint:
{debug_str}

What it means

Generic Beam type-hint check failure: when `type_check_inputs` runs, each declared input hint is compared against the actual runtime type hints of the incoming pvalueish. Inconsistency raises TypeCheckError with the transform label, required hint, actual type, offending argument name, and the full debug type hint string.

Solutions

Fix the actual type flowing in: adjust the producing transform so its output matches the declared input hint.
Relax or correct the consumer's input hint via `with_input_types()` or typed DoFn annotations to reflect real data.
Add an explicit `beam.Map(...).with_output_types(ExpectedType)` adapter between the mismatched stages.
Inspect `Full type hint:` in the message to pinpoint exactly which argument diverged.

Example fix

# before
beam.ParDo(WordCountFn()).with_input_types(int)
# after
beam.ParDo(WordCountFn()).with_input_types(str)

Defensive patterns

Strategy: validation

Validate before calling

from apache_beam import typehints
assert typehints.is_consistent_with(actual_type, hint), f'{actual_type} != {hint}'

Type guard

def input_types_match(transform, pcoll):
  from apache_beam import typehints
  hint = transform.get_type_hints().input_types[0] if transform.get_type_hints().input_types else typehints.Any
  return typehints.is_consistent_with(pcoll.element_type or typehints.Any, hint)

Try / catch

try:
  out = pc | 'typed_step' >> MyFn()
except TypeCheckError as e:
  log.error('%s', e)
  raise

Prevention

Use typed DoFn process signatures so hints stay in sync with code.
Convert element types explicitly with beam.Map and with_output_types between stages.
Review the 'Full type hint' debug output when a check fails instead of disabling checks.

When it happens

Trigger: A transform with declared input type hints (via `with_input_types`, typed DoFn annotations, or PTransform.type_check_inputs) receives a PCollection whose type hint is inconsistent with the declaration.

Common situations: Typed DoFns applied to loosely/incorrectly typed PCollections; using `Any`-implied producers downstream of strictly typed consumers; hints left stale after refactoring output element types.

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/6317281eb516e403. Report an issue: GitHub.

Appendix: source

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

        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,
                  hint=hint,
                  actual_type=bindings[arg],
                  arg=arg,
                  debug_str=type_hints.debug_str()))

  def _process_argspec_fn(self):
    """Returns an argspec of the function actually consuming the data.
    """
    raise NotImplementedError

  def make_fn(self, fn, has_side_inputs):
    # TODO(silviuc): Add comment describing that this is meant to be overriden
    # by methods detecting callables and wrapping them in DoFns.
    return fn

View on GitHub (pinned to 12126d8942)