{"record":{"id":"6c50bc140d804fb0","repo":"apache/beam","slug":"passed-object-instance-is-of-the-proper-type-but-differs-in","errorCode":null,"errorMessage":"Passed object instance is of the proper type, but differs in length from the hinted type. Expected a tuple of length %s, received a tuple of length %s.","messagePattern":"Passed object instance is of the proper type, but differs in length from the hinted type\\. Expected a tuple of length (.+?), received a tuple of length (.+?)\\.","errorType":"validation","errorClass":"CompositeTypeHintError","httpStatus":null,"severity":"error","filePath":"sdks/python/apache_beam/typehints/typehints.py","lineNumber":724,"sourceCode":"      \"\"\"Returns the type at the given index.\"\"\"\n      return self.tuple_types[idx]\n\n    def _consistent_with_check_(self, sub):\n      return (\n          isinstance(sub, self.__class__) and\n          len(sub.tuple_types) == len(self.tuple_types) and all(\n              is_consistent_with(sub_elem, elem)\n              for sub_elem, elem in zip(sub.tuple_types, self.tuple_types)))\n\n    def type_check(self, tuple_instance):\n      if not isinstance(tuple_instance, tuple):\n        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(","sourceCodeStart":706,"sourceCodeEnd":742,"githubUrl":"https://github.com/apache/beam/blob/12126d8942aaf848030c478b4c6a28c6af861c66/sdks/python/apache_beam/typehints/typehints.py#L706-L742","documentation":"Raised by TupleConstraint.type_check in apache_beam.typehints when a value passes the isinstance(tuple) check but its length differs from the number of element types declared in Tuple[...]. Beam validates type hints at pipeline runtime; a homogeneous-length tuple is part of the Tuple hint contract.","triggerScenarios":"Passing a tuple with the wrong arity to an input/output marked with a fixed-arity hint like Tuple[int, str] (e.g. a 3-element tuple against Tuple[int, str]), or a function returning a differently sized tuple than hinted.","commonSituations":"DoFn process methods yielding wrong-shaped tuples; ParDo outputs whose hinted Tuple was changed to add a field but producer code was not updated; unpacking/merging data streams of differing arity.","solutions":["Count the elements of the tuple you pass/yield and match it to the declared Tuple[...] arity","Update the producer code to yield the correct number of elements","If arity varies, change the hint to Tuple[T, ...] (homogeneous) or List[T] / Any","Re-run with beam debug flags to find the offending PTransform"],"exampleFix":"# before\nTuple[int, str]: yield (1, 'a', True)\n# after\nyield (1, 'a')  # matches Tuple[int, str]","handlingStrategy":"validation","validationCode":"if not isinstance(v, tuple) or len(v) != len(hint_tuple_types): raise ValueError(f'expected tuple of length {len(hint_tuple_types)}, got {v!r}')","typeGuard":"def is_fixed_tuple(v, n): return isinstance(v, tuple) and len(v) == n","tryCatchPattern":null,"preventionTips":["Keep producers and hints in the same module so arity changes are reviewed together","Use dataclasses/NamedTuple to make tuple shape explicit"],"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"}