{"record":{"id":"a1907ebd40311fd4","repo":"apache/beam","slug":"s-hint-type-constraint-violated-the-type-of-element-s-in-the","errorCode":null,"errorMessage":"%s hint type-constraint violated. The type of element #%s in the passed %s is incorrect. Expected an instance of type %s, instead received an instance of type %s.","messagePattern":"(.+?) hint type-constraint violated\\. The type of element #(.+?) in the passed (.+?) is incorrect\\. Expected an instance of type (.+?), instead received an instance of type (.+?)\\.","errorType":"validation","errorClass":"CompositeTypeHintError","httpStatus":null,"severity":"error","filePath":"sdks/python/apache_beam/typehints/typehints.py","lineNumber":291,"sourceCode":"    return (\n        isinstance(sub, self.__class__) and\n        is_consistent_with(sub.inner_type, self.inner_type))\n\n  def type_check(self, sequence_instance):\n    if not isinstance(sequence_instance, self._sequence_type):\n      raise CompositeTypeHintError(\n          \"%s type-constraint violated. Valid object instance \"\n          \"must be of type '%s'. Instead, an instance of '%s' \"\n          \"was received.\" % (\n              self._sequence_type.__name__.title(),\n              self._sequence_type.__name__.lower(),\n              sequence_instance.__class__.__name__))\n\n    for index, elem in enumerate(sequence_instance):\n      try:\n        check_constraint(self.inner_type, elem)\n      except SimpleTypeHintError:\n        raise CompositeTypeHintError(\n            '%s hint type-constraint violated. The type of element #%s in '\n            'the passed %s is incorrect. Expected an instance of type %s, '\n            'instead received an instance of type %s.' % (\n                repr(self),\n                index,\n                repr(self._sequence_type),\n                repr(self.inner_type),\n                elem.__class__.__name__))\n      except CompositeTypeHintError as e:\n        raise CompositeTypeHintError(\n            '%s hint type-constraint violated. The type of element #%s in '\n            'the passed %s is incorrect: %s' %\n            (repr(self), index, self._sequence_type.__name__, e))\n\n  def match_type_variables(self, concrete_type):\n    if isinstance(concrete_type, SequenceTypeConstraint):\n      return match_type_variables(self.inner_type, concrete_type.inner_type)\n    return {}","sourceCodeStart":273,"sourceCodeEnd":309,"githubUrl":"https://github.com/apache/beam/blob/12126d8942aaf848030c478b4c6a28c6af861c66/sdks/python/apache_beam/typehints/typehints.py#L273-L309","documentation":"Raised when a sequence (list/tuple/etc.) instance passes the container-class check but one of its elements fails the inner type constraint. Beam enumerates the sequence, calls check_constraint on each element, and converts a SimpleTypeHintError into a CompositeTypeHintError that names the offending index, expected element type, and the actual element's class.","triggerScenarios":"Calling type_check on a SequenceTypeConstraint (e.g. List[int]) where element #i is of the wrong type, such as a str mixed into a list of ints; check_constraint raises SimpleTypeHintError which is re-raised as this composite error.","commonSituations":"Mixed-type lists built from parsing (int(x) sometimes yielding str); None slipping into a List[str] from a Map that can return None; CSV/JSON rows producing heterogeneous element types.","solutions":["Inspect the reported element index and coerce or fix that element to the expected type before it reaches the typed transform.","Sanitize data upstream with beam.Map to convert/skip bad elements, e.g. filter None or cast values.","Loosen the hint to Union[...] if the data legitimately contains multiple types.","Add a validation step (beam.Map with asserts) before the typed stage to catch bad records early."],"exampleFix":"# before\nrows = ['1', 'two', '3']  # hinted List[int]\n# after\nrows = [int(x) for x in rows if x.isdigit()]  # all elements are int","handlingStrategy":"validation","validationCode":"def validate_seq(seq, elem_type):\n    assert isinstance(seq, (list, tuple))\n    for i, x in enumerate(seq):\n        if not isinstance(x, elem_type):\n            raise TypeError(f'element #{i} is {type(x).__name__}, expected {elem_type.__name__}')\n    return seq","typeGuard":"def all_of_type(seq, elem_type):\n    return isinstance(seq, (list, tuple)) and all(isinstance(x, elem_type) for x in seq)","tryCatchPattern":"try:\n    result = typed_transform.expand(pcoll)\nexcept CompositeTypeHintError as e:\n    # message contains offending index and expected type\n    logger.error('bad element: %s', e)\n    raise","preventionTips":["Sanitize/parse values (int(), float()) before typed stages","Filter out None and malformed records upstream","Prefer Optional[...] hints when values can be absent"],"tags":["python","apache-beam","typehints","element-type"],"backgroundTag":"type-mismatch","analyzedSha":"12126d8942aaf848030c478b4c6a28c6af861c66","analyzedAt":"2026-09-13T01:50:10.254Z","contentChangedAt":"2026-09-13T01:50:10.254Z","schemaVersion":2},"datasetVersion":"2026-09-14T21:17:11.552Z"}