apache/beam · error · ValueError

Tuple input to must have two components. Found .

Error message

Tuple input to %s must have two components. Found %s.

What it means

coerce_to_kv_type only accepts a 2-component TupleConstraint when coercing a hint into a KV type. A tuple hint with 1 or 3+ components cannot represent a key/value pair, so Beam raises. This happens during type inference for transforms like CombinePerKey, GroupByKey, or CoGroupByKey.

Solutions

1. Emit exactly 2-tuples: pc | beam.Map(lambda x: (x.key, x.value)).
2. Use beam.KV(K, V) / Tuple[Tuple[K, V]] type hints so inference fails early and clearly.
3. Restructure: pack extra fields into the value, e.g. (k, (v, extra)) instead of (k, v, extra).
4. If you don't need keying, use a non-KV transform such as beam.CombineGlobally with a custom combiner.

Example fix

// before
pc | beam.CombinePerKey(sum)  # elements are (k, v, extra)
// after
pc | beam.Map(lambda x: (x[0], (x[1], x[2]))) | beam.CombinePerKey(my_fn)

from apache_beam.typehints import Tuple
if not (isinstance(hint, tuple) or (hasattr(hint, 'tuple_types') and len(hint.tuple_types) == 2)):
    raise TypeError('KV transforms need 2-tuples')

def is_kv_tuple(t) -> bool:
    return isinstance(t, tuple) and len(t) == 2

try:
    kv = coerce_to_kv_type(element_type, consumer)
except ValueError as e:
    log.error('restructure PCollection to emit 2-tuples: %s', e)
    raise

When it happens

Trigger: Passing a PCollection of Tuple[int, str, bool] (or 1-tuples) into a KV-requiring transform, or calling coerce_to_kv_type(element_type, consumer) with such a hint.

Common situations: Emitting 3-field tuples from a DoFn then feeding GroupByKey/CombinePerKey; older Beam pipelines after moving from lambda returns of triples to KV transforms; accidental use of namedtuple with wrong arity.

Understand the failure class

Background: Schema validation failed / invalid input schema: payload rejected because its shape doesn't match the expected schema — this error's family across 28 libraries.

Related errors

• Input to must be compatible with KV[Any, Any]. Found .
• Length of parameters to a KV type-hint must be exactly 2…
• Parameter to KV type-hint must be a tuple of types: KV[..…
• 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/687b77d276370d02. Report an issue: GitHub.

Appendix: source

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

def coerce_to_kv_type(element_type, label=None, side_input_producer=None):
  """Attempts to coerce element_type to a compatible kv type.

  Raises an error on failure.
  """
  if side_input_producer:
    consumer = 'side-input of %r (producer: %r)' % (label, side_input_producer)
  else:
    consumer = '%r' % label

  # If element_type is not specified, then treat it as `Any`.
  if not element_type:
    return KV[Any, Any]
  elif isinstance(element_type, TupleHint.TupleConstraint):
    if len(element_type.tuple_types) == 2:
      return element_type
    else:
      raise ValueError(
          "Tuple input to %s must have two components. "
          "Found %s." % (consumer, element_type))
  elif isinstance(element_type, AnyTypeConstraint):
    # `Any` type needs to be replaced with a KV[Any, Any] to
    # satisfy the KV form.
    return KV[Any, Any]
  elif isinstance(element_type, UnionConstraint):
    union_types = [coerce_to_kv_type(t) for t in element_type.union_types]
    return KV[Union[tuple(t.tuple_types[0] for t in union_types)],
              Union[tuple(t.tuple_types[1] for t in union_types)]]
  else:
    # TODO: Possibly handle other valid types.
    raise ValueError(
        "Input to %s must be compatible with KV[Any, Any]. "
        "Found %s." % (consumer, element_type))

View on GitHub (pinned to 12126d8942)