{"record":{"id":"93e6cd3ae2f3ace6","repo":"apache/beam","slug":"s-hint-type-constraint-violated-the-type-of-element-s-in-the-93e6cd","errorCode":null,"errorMessage":"%s hint type-constraint violated. The type of element #%s in the passed tuple is incorrect. %s","messagePattern":"(.+?) hint type-constraint violated\\. The type of element #(.+?) in the passed tuple is incorrect\\. (.+?)","errorType":"validation","errorClass":"CompositeTypeHintError","httpStatus":null,"severity":"error","filePath":"sdks/python/apache_beam/typehints/typehints.py","lineNumber":742,"sourceCode":"        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(\n          bind_type_variables(t, bindings) for t in self.tuple_types)\n      if bound_tuple_types == self.tuple_types:\n        return self\n      return Tuple[bound_tuple_types]\n\n  def __getitem__(self, type_params):","sourceCodeStart":724,"sourceCodeEnd":760,"githubUrl":"https://github.com/apache/beam/blob/12126d8942aaf848030c478b4c6a28c6af861c66/sdks/python/apache_beam/typehints/typehints.py#L724-L760","documentation":"Raised by TupleConstraint.type_check when a nested element fails with a CompositeTypeHintError (e.g. a nested Tuple/List/Dict constraint). It wraps the inner error message into a positioned message for the outer tuple hint.","triggerScenarios":"An element that must itself satisfy a composite hint fails, e.g. Tuple[Tuple[int, int], str] receiving ((1,), 'x'); the inner error is re-raised with the outer tuple's element position.","commonSituations":"Deeply nested tuple structures in key/value payloads; one nested level changed shape without updating nested hints.","solutions":["Read the wrapped inner error (%s) to find the deepest failing level","Fix the nested structure to match the nested hint","Update nested hints if the data model legitimately changed"],"exampleFix":"# before\nTuple[Tuple[int, int], str]: yield ((1,), 'x')\n# after\nyield ((1, 2), 'x')","handlingStrategy":"validation","validationCode":"def check_nested(tpl, outer):\n    (inner_t, s), = None, None\n    if not (isinstance(tpl, tuple) and len(tpl)==2 and isinstance(tpl[0], tuple) and len(tpl[0])==2): raise ValueError('nested shape mismatch')","typeGuard":"def is_nested_pair(t): return isinstance(t, tuple) and len(t)==2 and isinstance(t[0], tuple)","tryCatchPattern":null,"preventionTips":["Validate nested structures with a schema check before the pipeline","Keep nested hint definitions next to the data-producing code"],"tags":["python","apache-beam","type-hints","nested-types"],"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"}