apache/beam · error · CompositeTypeHintError

%s type-constraint violated. Valid object instance must be o

Error message

%s type-constraint violated. Valid object instance must be of type '%s'. Instead, an instance of '%s' was received.

What it means

Apache Beam's typehints module raises CompositeTypeHintError from SequenceTypeConstraint.type_check when a value annotated as a sequence type-hint (e.g. List[int]) is not an instance of the expected Python sequence container class. The library validates PTransform inputs/outputs against declared type hints and fails fast when the concrete object's class differs from the constraint's sequence type (list, tuple, set, etc.).

Source

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

  def __hash__(self):
    return hash(self.inner_type) ^ 13 * hash(type(self))

  def _inner_types(self):
    yield self.inner_type

  def _constraint_for_index(self, idx):
    """Returns the type at the given index."""
    return self.inner_type

  def _consistent_with_check_(self, sub):
    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),

View on GitHub (pinned to 12126d8942)

Solutions

Make the passed value an instance of the required sequence type (e.g. wrap it in list(...) or tuple(...) as the hint requires).
Update the type hint (with_input_types/with_output_types or annotation) to match the actual container class produced.
Use typing.Any or a broader constraint temporarily to isolate which pipeline stage produces the wrong container.
Log sequence_instance.__class__ at the failing stage to confirm which element path is being type-checked.

Example fix

# before
p | 'parse' >> beam.Map(lambda s: (s[0], int(s[1]))).with_output_types(List[Tuple[str, int]])
# after
p | 'parse' >> beam.Map(lambda s: [s[0], int(s[1])]).with_output_types(List[Tuple[str, int]])

Defensive patterns

Strategy: type-guard

Validate before calling

def assert_sequence(value, seq_type):
    if not isinstance(value, seq_type):
        raise TypeError(f'expected {seq_type.__name__}, got {type(value).__name__}')
    return value

Type guard

def is_list_of(value, elem_type):
    return isinstance(value, list) and all(isinstance(x, elem_type) for x in value)

Try / catch

try:
    run_typed_stage(pcoll)
except CompositeTypeHintError as e:
    logger.error('container type mismatch: %s', e)
    raise

Prevention

Keep hint containers and produced containers identical (list vs tuple vs set)
Add type checks in unit tests using beam.typehints.check_constraint on sample outputs
Run pipelines with --type_check_strict or default runtime type checking in CI

When it happens

Trigger: Passing an object whose class is not the constrained sequence type to a type_check call, e.g. annotating a transform with List[int] but producing a tuple, or vice versa; also triggered when check_constraint dispatches a SequenceTypeConstraint against a non-sequence instance.

Common situations: Mismatch between declared and actual container types (list vs tuple vs set) when wiring Beam pipelines; refactors that change a transform's output container without updating with_output_types; deserialized objects (e.g. from JSON) that arrive as lists where tuples were hinted.

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