apache/beam · error · CompositeTypeHintError

Mapping type-constraint violated. All passed instances must…

Error message

Mapping type-constraint violated. All passed instances must be of type Mapping. %s is of type %s.

What it means

Mapping[...] runtime type checking requires the checked instance to be an instance of collections.abc.Mapping. If a non-mapping object (list, set, custom class) is passed where a Mapping[K, V] hint applies, this CompositeTypeHintError is raised before any key/value checks.

Solutions

Convert the result to a real mapping: dict(pairs)
Change the hint to List[Tuple[K, V]] or Iterable[Tuple[K, V]] if the data is a sequence of pairs
Make the custom container register/implement collections.abc.Mapping

Example fix

// before
p | beam.Map(lambda xs: [(k, v) for k, v in xs]).with_output_types(Mapping[str, int])
// after
p | beam.Map(lambda xs: dict(xs)).with_output_types(Mapping[str, int])

Defensive patterns

Strategy: type-guard

Validate before calling

import collections.abc
assert isinstance(result, collections.abc.Mapping), type(result)

Type guard

def is_mapping(obj):
    return isinstance(obj, collections.abc.Mapping)

Try / catch

try:
    typecheck.validate(Mapping[str, int], result)
except CompositeTypeHintError as e:
    if 'must be of type Mapping' in str(e):
        result = dict(result)

Prevention

Convert pair-lists to dict before returning
Know the ABC registrations of your container classes
Prefer dict/OrderedDict when a Mapping hint is used

When it happens

Trigger: Annotating an output as Mapping[int, str] but producing a list of pairs, a pandas Series, a namedtuple, or a custom container that does not implement the Mapping ABC; running with type_check=True.

Common situations: Confusing typing.List[Tuple[K,V]] with Mapping[K,V]; returning a collections.OrderedDict is fine, but returning a plain iterator of pairs is not; wrappers like dict subclasses that do not register as Mapping (rare) also trigger it.

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

Appendix: source

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

                type_desc,
                repr(expected_type),
                inner_error_message,
            ))
      else:
        raise CompositeTypeHintError(
            '%s hint %s-type constraint violated. All %ss should be of '
            'type %s. Instead, %s is of type %s.' % (
                repr(self),
                type_desc,
                type_desc,
                repr(expected_type),
                instance,
                instance.__class__.__name__,
            ))

    def type_check(self, instance):
      if not isinstance(instance, abc.Mapping):
        raise CompositeTypeHintError(
            'Mapping type-constraint violated. All passed instances must be of '
            'type Mapping. %s is of type %s.' %
            (instance, instance.__class__.__name__))

      for key, value in instance.items():
        try:
          check_constraint(self.key_type, key)
        except CompositeTypeHintError as e:
          self._raise_type_error(True, key, str(e))
        except SimpleTypeHintError:
          self._raise_type_error(True, key)

        try:
          check_constraint(self.value_type, value)
        except CompositeTypeHintError as e:
          self._raise_type_error(False, value, str(e))
        except SimpleTypeHintError:
          self._raise_type_error(False, value)

View on GitHub (pinned to 12126d8942)