apache/beam · error · CompositeTypeHintError

%s hint type-constraint violated. The type of element #%s in

Error message

%s hint type-constraint violated. The type of element #%s in the passed %s is incorrect. Expected an instance of type %s, instead received an instance of type %s.

What it means

Raised when a sequence (list/tuple/etc.) instance passes the container-class check but one of its elements fails the inner type constraint. Beam enumerates the sequence, calls check_constraint on each element, and converts a SimpleTypeHintError into a CompositeTypeHintError that names the offending index, expected element type, and the actual element's class.

Source

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

    return (
        isinstance(sub, self.__class__) and
        is_consistent_with(sub.inner_type, self.inner_type))

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

    for index, elem in enumerate(sequence_instance):
      try:
        check_constraint(self.inner_type, elem)
      except SimpleTypeHintError:
        raise CompositeTypeHintError(
            '%s hint type-constraint violated. The type of element #%s in '
            'the passed %s is incorrect. Expected an instance of type %s, '
            'instead received an instance of type %s.' % (
                repr(self),
                index,
                repr(self._sequence_type),
                repr(self.inner_type),
                elem.__class__.__name__))
      except CompositeTypeHintError as e:
        raise CompositeTypeHintError(
            '%s hint type-constraint violated. The type of element #%s in '
            'the passed %s is incorrect: %s' %
            (repr(self), index, self._sequence_type.__name__, e))

  def match_type_variables(self, concrete_type):
    if isinstance(concrete_type, SequenceTypeConstraint):
      return match_type_variables(self.inner_type, concrete_type.inner_type)
    return {}

View on GitHub (pinned to 12126d8942)

Solutions

1. Inspect the reported element index and coerce or fix that element to the expected type before it reaches the typed transform.
2. Sanitize data upstream with beam.Map to convert/skip bad elements, e.g. filter None or cast values.
3. Loosen the hint to Union[...] if the data legitimately contains multiple types.
4. Add a validation step (beam.Map with asserts) before the typed stage to catch bad records early.

Example fix

# before
rows = ['1', 'two', '3']  # hinted List[int]
# after
rows = [int(x) for x in rows if x.isdigit()]  # all elements are int

def validate_seq(seq, elem_type):
    assert isinstance(seq, (list, tuple))
    for i, x in enumerate(seq):
        if not isinstance(x, elem_type):
            raise TypeError(f'element #{i} is {type(x).__name__}, expected {elem_type.__name__}')
    return seq

def all_of_type(seq, elem_type):
    return isinstance(seq, (list, tuple)) and all(isinstance(x, elem_type) for x in seq)

try:
    result = typed_transform.expand(pcoll)
except CompositeTypeHintError as e:
    # message contains offending index and expected type
    logger.error('bad element: %s', e)
    raise

When it happens

Trigger: Calling type_check on a SequenceTypeConstraint (e.g. List[int]) where element #i is of the wrong type, such as a str mixed into a list of ints; check_constraint raises SimpleTypeHintError which is re-raised as this composite error.

Common situations: Mixed-type lists built from parsing (int(x) sometimes yielding str); None slipping into a List[str] from a Map that can return None; CSV/JSON rows producing heterogeneous element types.

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

• Unable to find BatchConverter for element_type={element_type
• batch type must be List[T] for element type T
• batch type must be np.ndarray or beam.typehints.batch.NumpyA
• TaggedOutput expects 2 type parameters, got {len(args)}: {t}
• %s type-constraint violated. Valid object instance must be o

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