apache/beam · error · TypeCheckError

According to type-hint expected %s should be of type %s. Ins

Error message

According to type-hint expected %s should be of type %s. Instead, received '%s', an instance of type %s.

What it means

TypeCheckCombineFn/TypeCheckWrapper's type_check validates a datum against a declared Beam type hint via typehints' validate. When the underlying hint check raises SimpleTypeHintError, it is re-raised as a TypeCheckError stating the expected type and the actual received instance. This is a runtime type-hint violation on inputs or outputs of a transform.

Source

Thrown at sdks/python/apache_beam/typehints/typecheck.py:211

          otherwise.

    Raises:
      TypeError: If 'datum' fails to type-check according to 'type_constraint'.
    """
    datum_type = 'input' if is_input else 'output'

    try:
      check_constraint(type_constraint, datum)
    except CompositeTypeHintError as e:
      _, _, tb = sys.exc_info()
      raise TypeCheckError(e.args[0]).with_traceback(tb)
    except SimpleTypeHintError:
      error_msg = (
          "According to type-hint expected %s should be of type %s. "
          "Instead, received '%s', an instance of type %s." %
          (datum_type, type_constraint, datum, type(datum)))
      _, _, tb = sys.exc_info()
      raise TypeCheckError(error_msg).with_traceback(tb)


class TypeCheckCombineFn(core.CombineFn):
  """A wrapper around a CombineFn performing type-checking of input and output.
  """
  def __init__(self, combinefn, type_hints, label=None):
    self._combinefn = combinefn
    self._input_type_hint = type_hints.input_types
    self._output_type_hint = type_hints.simple_output_type(label)
    self._label = label

  def setup(self, *args, **kwargs):
    self._combinefn.setup(*args, **kwargs)

  def create_accumulator(self, *args, **kwargs):
    return self._combinefn.create_accumulator(*args, **kwargs)

  def add_input(self, accumulator, element, *args, **kwargs):

View on GitHub (pinned to 12126d8942)

Solutions

1. Inspect the received instance in the message and coerce data to the expected type before the transform.
2. Update the type hints to reflect the real data types.
3. Filter or route malformed records with a validation DoFn before the checked transform.
4. Enable debugging on the hint to get detailed violation info and fix at the source.

Example fix

// before
p | beam.CombineGlobally(SumCount()).with_input_types(int)  # data has '3' strings
// after
p | beam.Map(int) | beam.CombineGlobally(SumCount()).with_input_types(int)

def assert_hint(datum, constraint):
    apache_beam.typehints.typehints.validate(constraint, datum)
    return datum

def matches_hint(datum, constraint) -> bool:
    try:
        typehints.validate(constraint, datum)
        return True
    except Exception:
        return False

try:
    out = checked_transform(data)
except TypeCheckError as e:
    log.error('Hint violation: %s', e)
    raise

When it happens

Trigger: Calling type_check_output/type_check on data whose runtime type doesn't match the PCollection's declared type hint, e.g. a CombineFn input element or accumulator not matching with_input_types/with_output_types declarations.

Common situations: Side inputs or sources producing unexpected element types; hints written for one schema but data changed upstream; combining elements of mixed types (int vs float vs str).

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

• Pipeline type checking is enabled, however no output type-hi
• Unable to deterministically encode '%s' of type '%s', please
• Transform "{full_label}" was applied to the output of "{prod
• DoFn {self!r} yields element from both process and process_b
• Return value not iterable: %s: %s

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