apache/beam · error · TypeCheckError

Type-hint for violated

Error message

Type-hint for %s violated: %s

What it means

When a composite type-hint (container/generator/union constraint) is violated, _check_instance_type catches CompositeTypeHintError and re-raises it as TypeCheckError 'Type-hint for %s violated: %s', preserving the detailed sub-constraint failure from the composite checker.

Solutions

  1. Read the embedded CompositeTypeHintError detail in the message to locate the failing sub-element
  2. Fix or filter the offending element before it reaches the type-checked boundary
  3. Loosen the composite hint (List[Any], Union branches) if the data legitimately varies
  4. Add a Map/DoFn validation step upstream to sanitize elements before the hinted transform

Example fix

// before
@with_output_types(List[int])
def f(): return [1, 'two']
// after
@with_output_types(List[int])
def f(): return [1, int('2')]  # or hint List[Union[int, str]]
Defensive patterns

Strategy: validation

Validate before calling

def validate_elements(items, elem_constraint):
  for i, x in enumerate(items):
    try:
      check_constraint(elem_constraint, x)
    except Exception as e:
      raise ValueError(f'element {i} bad: {e}')

Type guard

def all_match(items, constraint):
  return all(matches_hint(x, constraint) for x in items)

Try / catch

try:
  pcoll | check_or_interleave(hint)
except TypeCheckError as e:
  log.error('composite hint violated: %s', e)  # detail names the sub-element

Prevention

When it happens

Trigger: A value passes its top-level type but fails inside the composite constraint, e.g. hinted List[int] but the list contains a str, or Dict[str, int] with a float value — raised from type_check, wrapper, process, add_input, extract_output, or check_or_interleave.

Common situations: Nested-container data with one bad element (a single malformed record in a batch); Optional/Union hints where the value matches none of the branches; elements produced by a changed upstream transform.

Understand the failure class

Background: Schema validation failed / invalid input schema: payload rejected because its shape doesn't match the expected schema — this error's family across 28 libraries.

Related errors

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

Appendix: source

Thrown at sdks/python/apache_beam/typehints/decorators.py:1045

    TypeCheckError: If 'instance' fails to meet the type-constraint of
      'type_constraint'.
  """
  hint_type = (
      "argument: '%s'" % var_name if var_name is not None else 'return type')

  try:
    check_constraint(type_constraint, instance)
  except SimpleTypeHintError:
    if verbose:
      verbose_instance = '%s, ' % instance
    else:
      verbose_instance = ''
    raise TypeCheckError(
        'Type-hint for %s violated. Expected an '
        'instance of %s, instead found %san instance of %s.' %
        (hint_type, type_constraint, verbose_instance, type(instance)))
  except CompositeTypeHintError as e:
    raise TypeCheckError('Type-hint for %s violated: %s' % (hint_type, e))


def _interleave_type_check(type_constraint, var_name=None):
  """Lazily type-check the type-hint for a lazily generated sequence type.

  This function can be applied as a decorator or called manually in a curried
  manner:
    * @_interleave_type_check(List[int])
      def gen():
        yield 5

    or

     * gen = _interleave_type_check(Tuple[int, int], 'coord_gen')(gen)

  As a result, all type-checking for the passed generator will occur at 'yield'
  time. This way, we avoid having to depleat the generator in order to
  type-check it.

View on GitHub (pinned to 12126d8942)