apache/beam · error · TypeError

Parameter to Mapping type-hint must be a tuple of types…

Error message

Parameter to Mapping type-hint must be a tuple of types: Mapping[.., ..].

What it means

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.

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

Example fix

// before
.with_output_types(Mapping[str])
// after
.with_output_types(Mapping[str, int])

Defensive patterns

Strategy: type-guard

Validate before calling

def is_valid_mapping_hint(params):
    return isinstance(params, tuple) and len(params) == 2

Type guard

def valid_mapping_params(params):
    return isinstance(params, tuple) and len(params) == 2

Try / catch

try:
    hint = Mapping[params]
except TypeError as e:
    if 'Mapping type-hint' in str(e):
        hint = Mapping[Any, Any]

Prevention

Always two parameters for Mapping[K, V]
Use List[Tuple[K, V]] for pair sequences
Check generic arity with mypy

When it happens

Trigger: 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.

Common situations: 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.

Understand the failure class

Background: "Must be a positive integer", "Invalid value", "Unsupported": the invalid-argument-value error family, when a library rejects the value you pass — this error's family across 35 libraries.

Related errors

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

Appendix: source

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

      if isinstance(concrete_type, (MappingTypeConstraint, DictConstraint)):
        bindings = {}
        bindings.update(
            match_type_variables(self.key_type, concrete_type.key_type))
        bindings.update(
            match_type_variables(self.value_type, concrete_type.value_type))
        return bindings
      return {}

    def bind_type_variables(self, bindings):
      bound_key_type = bind_type_variables(self.key_type, bindings)
      bound_value_type = bind_type_variables(self.value_type, bindings)
      if (bound_key_type, bound_value_type) == (self.key_type, self.value_type):
        return self
      return Mapping[bound_key_type, bound_value_type]

  def __getitem__(self, type_params):
    if not isinstance(type_params, tuple):
      raise TypeError(
          'Parameter to Mapping type-hint must be a tuple of types: '
          'Mapping[.., ..].')

    if len(type_params) != 2:
      raise TypeError(
          'Length of parameters to a Mapping type-hint must be exactly 2. '
          'Passed parameters: %s, have a length of %s.' %
          (type_params, len(type_params)))

    key_type, value_type = type_params

    validate_composite_type_param(
        key_type, error_msg_prefix='Key-type parameter to a Mapping hint')
    validate_composite_type_param(
        value_type, error_msg_prefix='Value-type parameter to a Mapping hint')

    return self.MappingTypeConstraint(key_type, value_type)

View on GitHub (pinned to 12126d8942)