apache/beam · error · TypeCheckError

type hint violation at : expected , got

Error message

{type} type hint violation at {label}{context}: expected {hint}, got {actual_type}

What it means

When Beam type-checks PTransform inputs/outputs, each PCollection's element_type must be consistent with the declared type hint. If typehints.is_consistent_with fails, a TypeCheckError pinpointing the transform label and position is raised.

Solutions

  1. Fix the type hint to match actual element types (or vice versa) as indicated in the message.
  2. Verify the upstream PCollection's element_type (p.element_type) before applying the transform.
  3. Temporarily disable runtime type checking (e.g. pipeline options --runtime_type_check=False or type_check=False) to isolate where hints drift.

Example fix

// before
p | beam.Map(lambda x: str(x)).with_output_types(int)
// after
p | beam.Map(lambda x: str(x)).with_output_types(str)
Defensive patterns

Strategy: try-catch

Validate before calling

from apache_beam import typehints
assert typehints.is_consistent_with(pc.element_type, declared_hint), f"{pc.element_type} not consistent with {declared_hint}"

Try / catch

try:
  out = pcoll | transform
except TypeCheckError as e:
  print(f"Hint mismatch at {e}; check upstream element_type: {pcoll.element_type}")
  raise

Prevention

When it happens

Trigger: Applying a transform whose declared input/output hint doesn't match the actual element_type of the PCollection at runtime — e.g. hinting int while the PCollection holds str, or mismatched dict value types.

Common situations: Chaining transforms where an upstream transform changes element type silently; stale hints after refactoring; wrong hints on tagged outputs.

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

Appendix: source

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

      return
    arg_hints, kwarg_hints = hints
    # Output types can have kwargs for tagged output types.
    if arg_hints and kwarg_hints and input_or_output != 'output':
      raise TypeCheckError(
          'PTransform cannot have both positional and keyword input type hints'
          ' without overriding %s._type_check_%s()' %
          (self.__class__, input_or_output))
    root_hint = (
        arg_hints[0] if len(arg_hints) == 1 else arg_hints or kwarg_hints)
    for context, pvalue_, hint in _ZipPValues().visit(pvalueish, root_hint):
      if isinstance(pvalue_, DoOutputsTuple):
        continue
      if pvalue_.element_type is None:
        # TODO(robertwb): It's a bug that we ever get here. (typecheck)
        continue
      if hint and not typehints.is_consistent_with(pvalue_.element_type, hint):
        at_context = ' %s %s' % (input_or_output, context) if context else ''
        raise TypeCheckError(
            '{type} type hint violation at {label}{context}: expected {hint}, '
            'got {actual_type}'.format(
                type=input_or_output.title(),
                label=self.label,
                context=at_context,
                hint=hint,
                actual_type=pvalue_.element_type))

  def _infer_output_coder(self, input_type=None, input_coder=None):
    # type: (...) -> Optional[coders.Coder]

    """Returns the output coder to use for output of this transform.

    The Coder returned here should not be wrapped in a WindowedValueCoder
    wrapper.

    Args:
      input_type: An instance of an allowed built-in type, a custom class, or a

View on GitHub (pinned to 12126d8942)