{"record":{"id":"362af606f35d90a3","repo":"apache/beam","slug":"s-hint-type-constraint-violated-s","errorCode":null,"errorMessage":"%s hint type-constraint violated: %s","messagePattern":"(.+?) hint type-constraint violated: (.+?)","errorType":"exception","errorClass":"CompositeTypeHintError","httpStatus":null,"severity":"error","filePath":"sdks/python/apache_beam/typehints/typehints.py","lineNumber":1339,"sourceCode":"    def __hash__(self):\n      return hash(self.yielded_type)\n\n    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):","sourceCodeStart":1321,"sourceCodeEnd":1357,"githubUrl":"https://github.com/apache/beam/blob/12126d8942aaf848030c478b4c6a28c6af861c66/sdks/python/apache_beam/typehints/typehints.py#L1321-L1357","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","solutions":["Read the inner message after 'violated:' to find the offending element and fix its type","Validate/normalize elements before yielding them","Adjust the hinted element type to match actual element types"],"exampleFix":"// before\np | beam.Map(lambda xs: (x for x in xs)).with_output_types(Iterable[Dict[str, int]])  # keys are ints\n// after\np | beam.Map(lambda xs: ({str(k): v for k, v in x.items()} for x in xs)).with_output_types(Iterable[Dict[str, int]])","handlingStrategy":"try-catch","validationCode":"ok = all(isinstance(x, element_type) for x in iterable)\n# check elements before emitting through an Iterable[T] hinted op","typeGuard":"def elements_match(iterable, element_type):\n    return all(isinstance(x, element_type) for x in iterable)","tryCatchPattern":"from apache_beam.typehints.exceptions import CompositeTypeHintError\ntry:\n    typecheck.validate(Iterable[element_hint], values)\nexcept CompositeTypeHintError as e:\n    log.error('element violation: %s', e)  # inner message follows 'violated:'","preventionTips":["Parse the inner message after 'violated:' for the real cause","Validate generator outputs in tests since lazy types are only enforced per element","Normalize element types before yielding"],"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"}