{"record":{"id":"b7342f9af864cee4","repo":"apache/beam","slug":"s-hint-type-constraint-violated-the-type-of-element-s-in-the-b7342f","errorCode":null,"errorMessage":"%s hint type-constraint violated. The type of element #%s in the passed %s is incorrect: %s","messagePattern":"(.+?) hint type-constraint violated\\. The type of element #(.+?) in the passed (.+?) is incorrect: (.+?)","errorType":"validation","errorClass":"CompositeTypeHintError","httpStatus":null,"severity":"error","filePath":"sdks/python/apache_beam/typehints/typehints.py","lineNumber":301,"sourceCode":"              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 {}\n\n  def bind_type_variables(self, bindings):\n    bound_inner_type = bind_type_variables(self.inner_type, bindings)\n    if bound_inner_type == self.inner_type:\n      return self\n    bound_self = copy.copy(self)\n    bound_self.inner_type = bound_inner_type\n    return bound_self\n\n","sourceCodeStart":283,"sourceCodeEnd":319,"githubUrl":"https://github.com/apache/beam/blob/12126d8942aaf848030c478b4c6a28c6af861c66/sdks/python/apache_beam/typehints/typehints.py#L283-L319","documentation":"When an element inside a constrained sequence fails with a CompositeTypeHintError (e.g. a nested List[Tuple[int, str]] whose inner tuple is wrong), Beam re-raises it wrapped in this error, preserving the outer hint repr, the failing element index, the sequence type, and the nested error message. It exists to give a full path/context for deeply nested composite type failures.","triggerScenarios":"type_check on a SequenceTypeConstraint whose element fails check_constraint with CompositeTypeHintError instead of SimpleTypeHintError — i.e. the bad element is itself a composite (nested list, tuple, dict) violating its own constraint.","commonSituations":"Nested structures like List[Tuple[str, int]] where one tuple has swapped or wrong-typed fields; lists of dicts hinted as List[KV[str, int]]; recursively built data where one branch has the wrong shape.","solutions":["Read the nested message appended after 'incorrect:' to find the deepest failing element and fix its type.","Correct the nested structure construction (e.g. ensure tuples have exactly the hinted arity and types).","Update hints to match the real nested shape if the data shape is intentional.","Write a small unit test with beam.Create(sample) and the typed transform to reproduce and fix the nested mismatch."],"exampleFix":"# before\nList[Tuple[str, int]] data: [('a', '1'), ('b', 2)]  # '1' is str\n# after\n[('a', 1), ('b', 2)]  # every tuple is (str, int)","handlingStrategy":"validation","validationCode":"def check_nested(rows):\n    for i, t in enumerate(rows):\n        assert isinstance(t, tuple) and len(t) == 2 and isinstance(t[0], str) and isinstance(t[1], int), f'row {i} bad: {t!r}'\n    return rows","typeGuard":"def is_tuple2(t, a, b):\n    return isinstance(t, tuple) and len(t) == 2 and isinstance(t[0], a) and isinstance(t[1], b)","tryCatchPattern":"try:\n    expand(pcoll)\nexcept CompositeTypeHintError as e:\n    logger.error('nested element failure: %s', e)  # tail of message names the deepest failure\n    raise","preventionTips":["Validate nested structures element-by-element in tests","Keep nested arity and ordering fixed when constructing tuples","Use dataclasses/NamedTuple + converters to normalize shapes early"],"tags":["python","apache-beam","typehints","nested-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-20T03:17:13.778Z"}