apache/beam · error · TypeError

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

Error message

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

What it means

DictHint.__getitem__ is a type guard on subscripted Dict[...] hints: the type parameters must arrive as a tuple of exactly two types (Dict[K, V]); a bare single type (e.g. Dict[str] missing the value type) fails this check at typehint-construction time.

Solutions

Use two parameters: Dict[str, int]
Convert dynamic params to a 2-tuple: Dict[tuple(params)] with len==2
Use Any for the un-constrained side, e.g. Dict[str, Any]

Example fix

# before
Dict[str]
# after
Dict[str, Any]

Defensive patterns

Strategy: type-guard

Validate before calling

assert isinstance(params, tuple) and len(params) == 2, 'Dict requires (K, V) tuple'

Type guard

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

Prevention

Always subscript Dict with two types
Use Any for unconstrained sides; coerce dynamic param lists to tuples

When it happens

Trigger: Dict[str] (one param); Dict[[str, int]] or other non-tuple containers; programmatically building params as a list.

Common situations: Typos in annotations; dynamic hint builders passing lists; porting typing.Dict usage where a single type argument was intended (e.g. Dict[str] is invalid there too, but errors differ).

Understand the failure class

Background: "Invalid ... format", "must be in format X", "does not look like a ..." — invalid argument format errors across CLI tools and libraries — this error's family across 17 libraries.

Related errors

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

Appendix: source

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

        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, 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)

View on GitHub (pinned to 12126d8942)