apache/beam · error · TypeError

Parameter to KV type-hint must be a tuple of types: KV[..…

Error message

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

What it means

KVHint.__getitem__ is a type guard on subscripted KV[...] hints: the parameters must be passed as a 2-tuple of types (KV[K, V]). Python delivered a single bare type instead of a tuple because the hint was written without a comma, e.g. KV[str] rather than KV[str, int].

Solutions

Pass exactly two parameters: KV[int, str]
If parameters are dynamic, pass a 2-tuple: KV[tuple(params)] with len==2
Use Tuple[...] directly if key/value semantics are not needed

Example fix

# before
KV([int, str])
# after
KV[int, str]

Defensive patterns

Strategy: type-guard

Validate before calling

assert isinstance(params, tuple), 'KV requires a tuple of types'

Type guard

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

Prevention

Always subscript KV with two literal types
In dynamic builders, coerce with tuple(params) and assert len==2

When it happens

Trigger: KV[int] (single param); KV[int, str, bool] without parentheses is actually KV[(int, str, bool)] — fine — but KV[int, str] written as a non-tuple like KV[[int, str]] or a generator/list.

Common situations: Typos like KV[int, str] where one arg is itself a list; dynamically building type parameters and passing a list instead of a tuple.

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

Appendix: source

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

  def __getitem__(self, t):
    validate_composite_type_param(t, error_msg_prefix='Parameter to List hint')

    return self.ListConstraint(t)


ListConstraint = ListHint.ListConstraint


class KVHint(CompositeTypeHint):
  """A KV type-hint, represents a Key-Value pair of a particular type.

  Internally, KV[X, Y] proxies to Tuple[X, Y]. A KV type-hint accepts only
  accepts exactly two type-parameters. The first represents the required
  key-type and the second the required value-type.
  """
  def __getitem__(self, type_params):
    if not isinstance(type_params, tuple):
      raise TypeError(
          'Parameter to KV type-hint must be a tuple of types: '
          'KV[.., ..].')

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

    return Tuple[type_params]


def key_value_types(kv):
  """Returns the key and value type of a KV type-hint.

  Args:
    kv: An instance of a TypeConstraint sub-class.
  Returns:

View on GitHub (pinned to 12126d8942)