apache/beam · error · TypeCheckError

Runtime type violation detected within %s: %s

Error message

Runtime type violation detected within %s: %s

What it means

TypeCheckCombineFn.add_input validates each element (and accumulator) against the combine fn's input type hint before delegating to the wrapped CombineFn. A TypeCheckError from that validation is re-raised with the label: 'Runtime type violation detected within %s'. It identifies which combine transform received a wrongly-typed element.

Source

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

    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):
    if self._input_type_hint:
      try:
        _check_instance_type(
            self._input_type_hint[0][0].tuple_types[1],
            element,
            'element',
            True)
      except TypeCheckError as e:
        error_msg = (
            'Runtime type violation detected within %s: '
            '%s' % (self._label, e))
        _, _, tb = sys.exc_info()
        raise TypeCheckError(error_msg).with_traceback(tb)
    return self._combinefn.add_input(accumulator, element, *args, **kwargs)

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

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

  def extract_output(self, accumulator, *args, **kwargs):
    result = self._combinefn.extract_output(accumulator, *args, **kwargs)
    if self._output_type_hint:
      try:
        _check_instance_type(
            self._output_type_hint.tuple_types[1], result, None, True)
      except TypeCheckError as e:
        error_msg = (
            'Runtime type violation detected within %s: '
            '%s' % (self._label, e))

View on GitHub (pinned to 12126d8942)

Solutions

1. Fix the message to find the bad element and coerce types upstream (e.g. Map(int)).
2. Adjust the CombineFn's input type hint to match actual data.
3. Add a validation step to filter/convert malformed elements before combining.
4. Wrap add_input with defensive conversion in a custom CombineFn.

Example fix

// before
p | beam.CombineGlobally(beam.combiners.SumCombineFn()).with_input_types(int)
// after
p | beam.Map(lambda x: int(x)) | beam.CombineGlobally(beam.combiners.SumCombineFn()).with_input_types(int)

def coerce_numeric(elements, t=int):
    return [t(x) if not isinstance(x, t) else x for x in elements]

def all_ints(xs) -> bool:
    return all(isinstance(x, int) and not isinstance(x, bool) for x in xs)

try:
    combined = pcoll | beam.CombineGlobally(fn)
except TypeCheckError as e:
    log.error('Combine input violation: %s', e)
    raise

When it happens

Trigger: During Combine/CombineGlobally with runtime type checking, add_input receives an element (or accumulator) whose type violates the declared input hint (e.g. adding a str to an int sum combine).

Common situations: Combining PCollections parsed from JSON/CSV where numbers arrive as strings; accumulate/merge mixing float and Decimal; hints declared at the transform not matching actual 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

• Transform "{full_label}" was applied to the output of "{prod
• Pipeline type checking is enabled, however no output type-hi
• CombineFn.setup and CombineFn.teardown are not supported wit
• Expected a CombineFn or callable, got %r
• combine_fn must be specified.

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