apache/beam · error · CompositeTypeHintError

hint type-constraint violated. Expected a iterator of type…

Error message

%s hint type-constraint violated. Expected a iterator of type %s. Instead received a iterator of type %s.

What it means

Raised when an element of an Iterable/Iterator/Generator hinted collection fails a simple (non-composite) type check. The message reports the expected yielded type and the concrete class of the actual element received. Thrown during runtime type validation when the hint is traversed.

Solutions

Convert elements to the hinted type before yielding (int(x), str(x), etc.)
Fix the hint to the real element type (Iterable[float] or Iterable[Union[int, float]])
Filter out elements of the wrong type before emitting

Example fix

// before
p | beam.Map(lambda xs: [x / 2 for x in xs]).with_output_types(Iterable[int])
// after
p | beam.Map(lambda xs: [int(x / 2) for x in xs]).with_output_types(Iterable[int])

Defensive patterns

Strategy: validation

Validate before calling

assert all(isinstance(x, int) for x in values), 'element type mismatch'

Type guard

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

Try / catch

try:
    typecheck.validate(Iterable[int], values)
except CompositeTypeHintError as e:
    log.error('iterator element wrong type: %s', e)
    values = [int(x) for x in values]

Prevention

Convert element types before yielding (int/str/float)
Account for numpy scalars and None in hints
Test DoFn outputs against hints locally with --type_check=strict

When it happens

Trigger: An op annotated Iterable[int] / Iterator[str] yields elements of a different simple type, e.g. .with_output_types(Iterable[int]) but floats are emitted; caught by Beam's type_check during pipeline validation or at direct runner runtime.

Common situations: Yielding None among results; numpy scalar vs int; PCollection of mixed-type rows from JSON parsing; float division producing floats where ints were hinted.

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

Appendix: source

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

    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):
  """A type constraint for WindowedValue objects.

  Mostly for internal use.

View on GitHub (pinned to 12126d8942)