{"record":{"id":"8d4cdbb4db596e0b","repo":"apache/beam","slug":"s-hint-type-constraint-violated-expected-a-iterator-of-type","errorCode":null,"errorMessage":"%s hint type-constraint violated. Expected a iterator of type %s. Instead received a iterator of type %s.","messagePattern":"(.+?) hint type-constraint violated\\. Expected a iterator of type (.+?)\\. Instead received a iterator of type (.+?)\\.","errorType":"exception","errorClass":"CompositeTypeHintError","httpStatus":null,"severity":"error","filePath":"sdks/python/apache_beam/typehints/typehints.py","lineNumber":1342,"sourceCode":"    def _inner_types(self):\n      yield self.yielded_type\n\n    def _consistent_with_check_(self, sub):\n      return (\n          isinstance(sub, self.__class__) and\n          is_consistent_with(sub.yielded_type, self.yielded_type))\n\n    def type_check(self, instance):\n      # Special case for lazy types, we only need to enforce the underlying\n      # type. This avoid having to compute the entirety of the generator/iter.\n      try:\n        check_constraint(self.yielded_type, instance)\n        return\n      except CompositeTypeHintError as e:\n        raise CompositeTypeHintError(\n            '%s hint type-constraint violated: %s' % (repr(self), str(e)))\n      except SimpleTypeHintError:\n        raise CompositeTypeHintError(\n            '%s hint type-constraint violated. Expected a iterator of type %s. '\n            'Instead received a iterator of type %s.' %\n            (repr(self), repr(self.yielded_type), instance.__class__.__name__))\n\n  def __getitem__(self, type_param):\n    validate_composite_type_param(\n        type_param, error_msg_prefix='Parameter to an Iterator hint')\n\n    return self.IteratorTypeConstraint(type_param)\n\n\nIteratorTypeConstraint = IteratorHint.IteratorTypeConstraint\n\n\nclass WindowedTypeConstraint(TypeConstraint, metaclass=GetitemConstructor):\n  \"\"\"A type constraint for WindowedValue objects.\n\n  Mostly for internal use.","sourceCodeStart":1324,"sourceCodeEnd":1360,"githubUrl":"https://github.com/apache/beam/blob/12126d8942aaf848030c478b4c6a28c6af861c66/sdks/python/apache_beam/typehints/typehints.py#L1324-L1360","documentation":"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.","triggerScenarios":"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.","commonSituations":"Yielding None among results; numpy scalar vs int; PCollection of mixed-type rows from JSON parsing; float division producing floats where ints were hinted.","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"],"exampleFix":"// before\np | beam.Map(lambda xs: [x / 2 for x in xs]).with_output_types(Iterable[int])\n// after\np | beam.Map(lambda xs: [int(x / 2) for x in xs]).with_output_types(Iterable[int])","handlingStrategy":"validation","validationCode":"assert all(isinstance(x, int) for x in values), 'element type mismatch'","typeGuard":"def is_iterable_of(iterable, element_type):\n    return all(isinstance(x, element_type) for x in iterable)","tryCatchPattern":"try:\n    typecheck.validate(Iterable[int], values)\nexcept CompositeTypeHintError as e:\n    log.error('iterator element wrong type: %s', e)\n    values = [int(x) for x in values]","preventionTips":["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"],"tags":["python","apache-beam","type-hints","iterable","runtime-type-check"],"backgroundTag":"type-mismatch","analyzedSha":"12126d8942aaf848030c478b4c6a28c6af861c66","analyzedAt":"2026-09-13T01:50:10.254Z","contentChangedAt":"2026-09-13T01:50:10.254Z","schemaVersion":2},"datasetVersion":"2026-09-20T03:17:13.778Z"}