apache/beam · error · TypeError

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

Error message

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

What it means

KVHint.__getitem__ received a tuple of type parameters whose length is not 2; a KV hint denotes exactly a key type and a value type, so KV[str, int, float] (or an empty KV[]) is rejected at typehint-construction time.

Solutions

1. Ensure exactly two type parameters: KV[int, str]
2. If the key/value pair comes from data, validate len==2 before subscripting
3. Split extra fields out or compose nested types, e.g. KV[int, Tuple[str, bool]]

Example fix

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

if len(params) != 2: raise ValueError(f'KV needs exactly 2 params, got {len(params)}')

def is_pair(t): return isinstance(t, tuple) and len(t) == 2

When it happens

Trigger: KV[int] — bare non-tuple single param actually hits the earlier check, but KV[(int,)] or KV[(int, str, bool)] (parenthesized 1- or 3-tuple) triggers this; dynamically building params with wrong count.

Common situations: Programmatic hint construction (e.g. KV[tuple(fields)]) where fields has != 2 items; misunderstanding that KV[int, str, bool] parses as a 3-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

• Input to must be compatible with KV[Any, Any]. Found .
• Parameter to KV type-hint must be a tuple of types: KV[..…
• Tuple input to must have two components. Found .
• According to type-hint expected
• All functions for a Combine PTransform must accept a single…

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

Appendix: source

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

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:
    A tuple: (key_type, value_type) if the passed type-hint is an instance of a
    KV type-hint, and (Any, Any) otherwise.
  """
  if isinstance(kv, TupleHint.TupleConstraint):
    return kv.tuple_types

View on GitHub (pinned to 12126d8942)