apache/beam · error · CompositeTypeHintError

hint type-constraint violated. The type of element # in the…

Error message

%s hint type-constraint violated. The type of element #%s in the passed tuple is incorrect. %s

What it means

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.

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

Example fix

# before
Tuple[Tuple[int, int], str]: yield ((1,), 'x')
# after
yield ((1, 2), 'x')

Defensive patterns

Strategy: validation

Validate before calling

def check_nested(tpl, outer):
    (inner_t, s), = None, None
    if not (isinstance(tpl, tuple) and len(tpl)==2 and isinstance(tpl[0], tuple) and len(tpl[0])==2): raise ValueError('nested shape mismatch')

Type guard

def is_nested_pair(t): return isinstance(t, tuple) and len(t)==2 and isinstance(t[0], tuple)

Prevention

Validate nested structures with a schema check before the pipeline
Keep nested hint definitions next to the data-producing code

When it happens

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

Common situations: Deeply nested tuple structures in key/value payloads; one nested level changed shape without updating nested hints.

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/93e6cd3ae2f3ace6. Report an issue: GitHub.

Appendix: source

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

        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(
              '%s hint type-constraint violated. The type of element #%s in '
              'the passed tuple is incorrect. %s' % (repr(self), type_pos, e))

    def match_type_variables(self, concrete_type):
      bindings = {}
      if isinstance(concrete_type, TupleConstraint):
        for a, b in zip(self.tuple_types, concrete_type.tuple_types):
          bindings.update(match_type_variables(a, b))
      return bindings

    def bind_type_variables(self, bindings):
      bound_tuple_types = tuple(
          bind_type_variables(t, bindings) for t in self.tuple_types)
      if bound_tuple_types == self.tuple_types:
        return self
      return Tuple[bound_tuple_types]

  def __getitem__(self, type_params):

View on GitHub (pinned to 12126d8942)