apache/beam · error · TypeError

Length of parameters to a Mapping type-hint must be exactly…

Error message

Length of parameters to a Mapping type-hint must be exactly 2. Passed parameters: %s, have a length of %s.

What it means

Mapping[...] type-hints must be parameterized with exactly two types (key and value). This TypeError is raised by Mapping.__getitem__ when a tuple whose length is not 2 is used to parameterize the hint.

Solutions

Reduce to exactly two parameters: Mapping[K, V]
Fold extra info into the value type (e.g. Mapping[K, Tuple[V1, V2]])
Use Any for sides you do not want to constrain

Example fix

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

Defensive patterns

Strategy: type-guard

Validate before calling

assert isinstance(params, tuple) and len(params) == 2, params

Type guard

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

Try / catch

try:
    hint = Mapping[k, v, extra]
except TypeError:
    hint = Mapping[k, Tuple[v, type(extra)]]

Prevention

Never pass more than two type params to Mapping
Bundle extra types into Tuple/Union on the value side
Run mypy over pipeline modules

When it happens

Trigger: Writing Mapping[int, str, float] (three parameters) or Mapping[int, str, ...] in an output-type annotation or type_check call.

Common situations: Copy-paste from nested generic syntax; thinking Mapping accepts extra params like variadic tuples; code generators emitting wrong arity.

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

Appendix: source

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

            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)


MappingTypeConstraint = MappingHint.MappingTypeConstraint


class IterableHint(CompositeTypeHint):

View on GitHub (pinned to 12126d8942)