apache/beam · error · CompositeTypeHintError

Passed object instance is of the proper type, but differs…

Error message

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.

What it means

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.

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

Example fix

# before
Tuple[int, str]: yield (1, 'a', True)
# after
yield (1, 'a')  # matches Tuple[int, str]

Defensive patterns

Strategy: validation

Validate before calling

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}')

Type guard

def is_fixed_tuple(v, n): return isinstance(v, tuple) and len(v) == n

Prevention

Keep producers and hints in the same module so arity changes are reviewed together
Use dataclasses/NamedTuple to make tuple shape explicit

When it happens

Trigger: 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.

Common situations: 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.

Understand the failure class

Background: Type mismatch errors: IllegalArgumentException, TypeError and type guards across 150 open-source libraries — this error's family across 150 libraries.

Related errors

AI-assisted analysis of apache/beam@12126d8942 (2026-09-13). Data as JSON: /api/errors/6c50bc140d804fb0. Report an issue: GitHub.

Appendix: source

Thrown at sdks/python/apache_beam/typehints/typehints.py:724

      """Returns the type at the given index."""
      return self.tuple_types[idx]

    def _consistent_with_check_(self, sub):
      return (
          isinstance(sub, self.__class__) and
          len(sub.tuple_types) == len(self.tuple_types) and all(
              is_consistent_with(sub_elem, elem)
              for sub_elem, elem in zip(sub.tuple_types, self.tuple_types)))

    def type_check(self, tuple_instance):
      if not isinstance(tuple_instance, tuple):
        raise CompositeTypeHintError(
            "Tuple type constraint violated. Valid object instance must be of "
            "type 'tuple'. Instead, an instance of '%s' was received." %
            tuple_instance.__class__.__name__)

      if len(tuple_instance) != len(self.tuple_types):
        raise CompositeTypeHintError(
            '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.' %
            (len(self.tuple_types), len(tuple_instance)))

      for type_pos, (expected, actual) in enumerate(zip(self.tuple_types,
                                                        tuple_instance)):
        try:
          check_constraint(expected, actual)
          continue
        except SimpleTypeHintError:
          raise CompositeTypeHintError(
              '%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.' %
              (repr(self), type_pos, repr(expected), actual.__class__.__name__))
        except CompositeTypeHintError as e:
          raise CompositeTypeHintError(

View on GitHub (pinned to 12126d8942)