{"record":{"id":"2c957721ce0b8190","repo":"apache/beam","slug":"s-hint-type-constraint-violated-the-type-of-element-s-in-the-2c9577","errorCode":null,"errorMessage":"%s hint type-constraint violated. The type of element #%s in the passed tuple 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 tuple 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":736,"sourceCode":"        raise CompositeTypeHintError(\n            \"Tuple type constraint violated. Valid object instance must be of \"\n            \"type 'tuple'. Instead, an instance of '%s' was received.\" %\n            tuple_instance.__class__.__name__)\n\n      if len(tuple_instance) != len(self.tuple_types):\n        raise CompositeTypeHintError(\n            'Passed object instance is of the proper type, but differs in '\n            'length from the hinted type. Expected a tuple of length %s, '\n            'received a tuple of length %s.' %\n            (len(self.tuple_types), len(tuple_instance)))\n\n      for type_pos, (expected, actual) in enumerate(zip(self.tuple_types,\n                                                        tuple_instance)):\n        try:\n          check_constraint(expected, actual)\n          continue\n        except SimpleTypeHintError:\n          raise CompositeTypeHintError(\n              '%s hint type-constraint violated. The type of element #%s in '\n              'the passed tuple is incorrect. Expected an instance of '\n              'type %s, instead received an instance of type %s.' %\n              (repr(self), type_pos, repr(expected), actual.__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 tuple is incorrect. %s' % (repr(self), type_pos, e))\n\n    def match_type_variables(self, concrete_type):\n      bindings = {}\n      if isinstance(concrete_type, TupleConstraint):\n        for a, b in zip(self.tuple_types, concrete_type.tuple_types):\n          bindings.update(match_type_variables(a, b))\n      return bindings\n\n    def bind_type_variables(self, bindings):\n      bound_tuple_types = tuple(","sourceCodeStart":718,"sourceCodeEnd":754,"githubUrl":"https://github.com/apache/beam/blob/12126d8942aaf848030c478b4c6a28c6af861c66/sdks/python/apache_beam/typehints/typehints.py#L718-L754","documentation":"Raised by TupleConstraint.type_check when element at position type_pos fails a SimpleTypeHintError check against the declared per-position type. It reports the expected type repr and the actual runtime class of the offending element.","triggerScenarios":"A tuple element whose runtime type differs from the corresponding hint entry, e.g. (1, 'a') checked against Tuple[int, int]; a bool/str slipping into a numeric slot.","commonSituations":"CSV/JSON rows parsed into tuples with mixed-type columns; accidentally swapped element order; None appearing where a concrete type is hinted.","solutions":["Inspect the reported element index and fix its runtime type","Check element ordering against the declared Tuple[...] order","Use Optional[...] in the hint if None is legitimate","Add a validation DoFn before the hinted transform to catch bad rows early"],"exampleFix":"# before\nTuple[int, int]: yield (1, 'a')\n# after\nyield (1, int('a'))  # or correct the data/coerce the type","handlingStrategy":"validation","validationCode":"for i, (el, t) in enumerate(zip(tpl, expected_types)):\n    if not isinstance(el, t): raise ValueError(f'element #{i} is {type(el).__name__}, expected {t}')","typeGuard":"def matches(tpl, types): return isinstance(tpl, tuple) and len(tpl)==len(types) and all(isinstance(e,t) for e,t in zip(tpl,types))","tryCatchPattern":null,"preventionTips":["Coerce types at data-ingestion boundaries","Avoid None where concrete types are hinted; use Optional[...]"],"tags":["python","apache-beam","type-hints","tuple"],"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"}