apache/beam · error · TypeError

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

Error message

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

What it means

Apache Beam's Dict[...] type-hint requires exactly two type parameters (key type and value type). The Dict class __getitem__ validates the subscription expression and raises TypeError when a tuple of length != 2 is passed. This happens at pipeline construction time when the type hint is written.

Solutions

Pass exactly two type parameters: Dict[key_type, value_type]
If only one dimension is known, use the wildcard Any for the other: Dict[int, Any]
Ensure the parameters form a tuple — write Dict[int, str], not Dict[[int, str]]

Example fix

// before
result = p | beam.Map(lambda x: x) .with_output_types(Dict[str])
// after
result = p | beam.Map(lambda x: x) .with_output_types(Dict[str, int])

Defensive patterns

Strategy: type-guard

Validate before calling

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

# call Dict[params] only if is_valid_dict_hint(params)

Type guard

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

Try / catch

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

Prevention

Always write Dict[K, V] with two parameters
Use Any for unconstrained sides
Lint annotations with mypy which flags wrong generic arity

When it happens

Trigger: Writing Dict[int] (missing value type), Dict[int, str, float] (extra parameter), or passing a non-parameterized hint list/tuple of wrong length to Dict[...] in @DoFn.process_element type annotations or ApplyOptions(type_check=True).

Common situations: Hand-writing annotations where the value type is forgotten (Dict[str] instead of Dict[str, int]); generating hints programmatically by passing a list like Dict[[int, str]] which is not a tuple, or a tuple of three types; copy-paste from typing.Dict habits.

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

Appendix: source

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

        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, self.key_type) == (bound_value_type, self.value_type):
        return self
      return Dict[bound_key_type, bound_value_type]

  def __getitem__(self, type_params):
    # Type param must be a (k, v) pair.
    if not isinstance(type_params, tuple):
      raise TypeError(
          'Parameter to Dict type-hint must be a tuple of types: '
          'Dict[.., ..].')

    if len(type_params) != 2:
      raise TypeError(
          'Length of parameters to a Dict 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 Dict hint')
    validate_composite_type_param(
        value_type, error_msg_prefix='Value-type parameter to a Dict hint')

    return self.DictConstraint(key_type, value_type)


DictConstraint = DictHint.DictConstraint


class SetHint(CompositeTypeHint):

View on GitHub (pinned to 12126d8942)