{"record":{"id":"2cbb49ff204bafeb","repo":"apache/beam","slug":"parameter-to-mapping-type-hint-must-be-a-tuple-of-types","errorCode":null,"errorMessage":"Parameter to Mapping type-hint must be a tuple of types: Mapping[.., ..].","messagePattern":"Parameter to Mapping type-hint must be a tuple of types: Mapping\\[\\.\\., \\.\\.\\]\\.","errorType":"validation","errorClass":"TypeError","httpStatus":null,"severity":"error","filePath":"sdks/python/apache_beam/typehints/typehints.py","lineNumber":1237,"sourceCode":"      if isinstance(concrete_type, (MappingTypeConstraint, DictConstraint)):\n        bindings = {}\n        bindings.update(\n            match_type_variables(self.key_type, concrete_type.key_type))\n        bindings.update(\n            match_type_variables(self.value_type, concrete_type.value_type))\n        return bindings\n      return {}\n\n    def bind_type_variables(self, bindings):\n      bound_key_type = bind_type_variables(self.key_type, bindings)\n      bound_value_type = bind_type_variables(self.value_type, bindings)\n      if (bound_key_type, bound_value_type) == (self.key_type, self.value_type):\n        return self\n      return Mapping[bound_key_type, bound_value_type]\n\n  def __getitem__(self, type_params):\n    if not isinstance(type_params, tuple):\n      raise TypeError(\n          'Parameter to Mapping type-hint must be a tuple of types: '\n          'Mapping[.., ..].')\n\n    if len(type_params) != 2:\n      raise TypeError(\n          'Length of parameters to a Mapping type-hint must be exactly 2. '\n          'Passed parameters: %s, have a length of %s.' %\n          (type_params, len(type_params)))\n\n    key_type, value_type = type_params\n\n    validate_composite_type_param(\n        key_type, error_msg_prefix='Key-type parameter to a Mapping hint')\n    validate_composite_type_param(\n        value_type, error_msg_prefix='Value-type parameter to a Mapping hint')\n\n    return self.MappingTypeConstraint(key_type, value_type)\n","sourceCodeStart":1219,"sourceCodeEnd":1255,"githubUrl":"https://github.com/apache/beam/blob/12126d8942aaf848030c478b4c6a28c6af861c66/sdks/python/apache_beam/typehints/typehints.py#L1219-L1255","documentation":"Mapping[...] subscription requires a tuple of exactly two type parameters. __getitem__ raises TypeError when the parameter passed is not a tuple — e.g. Mapping[int] (single parameter) or Mapping[SomeList]. It fails at hint-construction time, before any pipeline runs.","triggerScenarios":"Writing Mapping[int] (one param), Mapping[K, V, W] then hitting the follow-up length error, or programmatically passing a list/other non-tuple as the type parameter.","commonSituations":"Typo where the comma is forgotten; translating typing.Mapping usage where a generic alias was passed instead of concrete types; generating hints dynamically and passing collections instead of a tuple.","solutions":["Provide exactly two parameters: Mapping[key_type, value_type]","Use Any for unknown sides: Mapping[str, Any]","If you actually want a sequence hint, use List[Tuple[K, V]] instead"],"exampleFix":"// before\n.with_output_types(Mapping[str])\n// after\n.with_output_types(Mapping[str, int])","handlingStrategy":"type-guard","validationCode":"def is_valid_mapping_hint(params):\n    return isinstance(params, tuple) and len(params) == 2","typeGuard":"def valid_mapping_params(params):\n    return isinstance(params, tuple) and len(params) == 2","tryCatchPattern":"try:\n    hint = Mapping[params]\nexcept TypeError as e:\n    if 'Mapping type-hint' in str(e):\n        hint = Mapping[Any, Any]","preventionTips":["Always two parameters for Mapping[K, V]","Use List[Tuple[K, V]] for pair sequences","Check generic arity with mypy"],"tags":["python","apache-beam","type-hints","mapping"],"backgroundTag":"invalid-argument-value","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"}