{"record":{"id":"cd16c2465ad8e02d","repo":"apache/beam","slug":"mapping-type-constraint-violated-all-passed-instances-must","errorCode":null,"errorMessage":"Mapping type-constraint violated. All passed instances must be of type Mapping. %s is of type %s.","messagePattern":"Mapping type-constraint violated\\. All passed instances must be of type Mapping\\. (.+?) is of type (.+?)\\.","errorType":"exception","errorClass":"CompositeTypeHintError","httpStatus":null,"severity":"error","filePath":"sdks/python/apache_beam/typehints/typehints.py","lineNumber":1198,"sourceCode":"                type_desc,\n                repr(expected_type),\n                inner_error_message,\n            ))\n      else:\n        raise CompositeTypeHintError(\n            '%s hint %s-type constraint violated. All %ss should be of '\n            'type %s. Instead, %s is of type %s.' % (\n                repr(self),\n                type_desc,\n                type_desc,\n                repr(expected_type),\n                instance,\n                instance.__class__.__name__,\n            ))\n\n    def type_check(self, instance):\n      if not isinstance(instance, abc.Mapping):\n        raise CompositeTypeHintError(\n            'Mapping type-constraint violated. All passed instances must be of '\n            'type Mapping. %s is of type %s.' %\n            (instance, instance.__class__.__name__))\n\n      for key, value in instance.items():\n        try:\n          check_constraint(self.key_type, key)\n        except CompositeTypeHintError as e:\n          self._raise_type_error(True, key, str(e))\n        except SimpleTypeHintError:\n          self._raise_type_error(True, key)\n\n        try:\n          check_constraint(self.value_type, value)\n        except CompositeTypeHintError as e:\n          self._raise_type_error(False, value, str(e))\n        except SimpleTypeHintError:\n          self._raise_type_error(False, value)","sourceCodeStart":1180,"sourceCodeEnd":1216,"githubUrl":"https://github.com/apache/beam/blob/12126d8942aaf848030c478b4c6a28c6af861c66/sdks/python/apache_beam/typehints/typehints.py#L1180-L1216","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","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"],"exampleFix":"// before\np | beam.Map(lambda xs: [(k, v) for k, v in xs]).with_output_types(Mapping[str, int])\n// after\np | beam.Map(lambda xs: dict(xs)).with_output_types(Mapping[str, int])","handlingStrategy":"type-guard","validationCode":"import collections.abc\nassert isinstance(result, collections.abc.Mapping), type(result)","typeGuard":"def is_mapping(obj):\n    return isinstance(obj, collections.abc.Mapping)","tryCatchPattern":"try:\n    typecheck.validate(Mapping[str, int], result)\nexcept CompositeTypeHintError as e:\n    if 'must be of type Mapping' in str(e):\n        result = dict(result)","preventionTips":["Convert pair-lists to dict before returning","Know the ABC registrations of your container classes","Prefer dict/OrderedDict when a Mapping hint is used"],"tags":["python","apache-beam","type-hints","mapping","runtime-type-check"],"backgroundTag":"type-mismatch","analyzedSha":"12126d8942aaf848030c478b4c6a28c6af861c66","analyzedAt":"2026-09-13T01:50:10.254Z","contentChangedAt":"2026-09-13T01:50:10.254Z","schemaVersion":2},"datasetVersion":"2026-09-20T03:17:13.778Z"}