apache/beam · error · CompositeTypeHintError

hint type-constraint violated

Error message

%s hint type-constraint violated: %s

What it means

For lazy/composite iterable hints (e.g. Iterable[T], Generator[T]), Beam wraps the inner validation failure: when checking an element of the iterable raises a CompositeTypeHintError, it is re-raised with this outer message prefix identifying the hint. The inner message (after the colon) describes the actual per-element violation.

Solutions

  1. Read the inner message after 'violated:' to find the offending element and fix its type
  2. Validate/normalize elements before yielding them
  3. Adjust the hinted element type to match actual element types

Example fix

// before
p | beam.Map(lambda xs: (x for x in xs)).with_output_types(Iterable[Dict[str, int]])  # keys are ints
// after
p | beam.Map(lambda xs: ({str(k): v for k, v in x.items()} for x in xs)).with_output_types(Iterable[Dict[str, int]])
Defensive patterns

Strategy: try-catch

Validate before calling

ok = all(isinstance(x, element_type) for x in iterable)
# check elements before emitting through an Iterable[T] hinted op

Type guard

def elements_match(iterable, element_type):
    return all(isinstance(x, element_type) for x in iterable)

Try / catch

from apache_beam.typehints.exceptions import CompositeTypeHintError
try:
    typecheck.validate(Iterable[element_hint], values)
except CompositeTypeHintError as e:
    log.error('element violation: %s', e)  # inner message follows 'violated:'

Prevention

When it happens

Trigger: A pipeline op annotated with Iterable[T]/Iterator[T] yields elements violating T, and the element failure itself is a composite error (e.g. T = Dict[str, int] and an element dict has a bad key), with type checking enabled.

Common situations: Generators lazily producing records of mixed shape; nested hints like Iterable[Dict[str, int]] where the element dicts drift; default type checking in Beam runners catching a bad DoFn output.

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

Appendix: source

Thrown at sdks/python/apache_beam/typehints/typehints.py:1339

    def __hash__(self):
      return hash(self.yielded_type)

    def _inner_types(self):
      yield self.yielded_type

    def _consistent_with_check_(self, sub):
      return (
          isinstance(sub, self.__class__) and
          is_consistent_with(sub.yielded_type, self.yielded_type))

    def type_check(self, instance):
      # Special case for lazy types, we only need to enforce the underlying
      # type. This avoid having to compute the entirety of the generator/iter.
      try:
        check_constraint(self.yielded_type, instance)
        return
      except CompositeTypeHintError as e:
        raise CompositeTypeHintError(
            '%s hint type-constraint violated: %s' % (repr(self), str(e)))
      except SimpleTypeHintError:
        raise CompositeTypeHintError(
            '%s hint type-constraint violated. Expected a iterator of type %s. '
            'Instead received a iterator of type %s.' %
            (repr(self), repr(self.yielded_type), instance.__class__.__name__))

  def __getitem__(self, type_param):
    validate_composite_type_param(
        type_param, error_msg_prefix='Parameter to an Iterator hint')

    return self.IteratorTypeConstraint(type_param)


IteratorTypeConstraint = IteratorHint.IteratorTypeConstraint


class WindowedTypeConstraint(TypeConstraint, metaclass=GetitemConstructor):

View on GitHub (pinned to 12126d8942)