apache/beam · error · TypeCheckError

Bad tuple arguments for

Error message

Bad tuple arguments for %s: expected %s, got %s

What it means

_unpack_positional_arg_hints verifies that a hint given for a *args-style list argument is consistent with a Tuple[Any, ..., Any] of the list's length. When the hint cannot match the tuple arity/shape (e.g. hint is int for a 3-element list, or a variadic Tuple where a fixed one is needed), it raises TypeCheckError.

Solutions

1. Change the hint to a fixed-length Tuple matching the list length, e.g. Tuple[int, int, int] for 3 elements
2. If the argument is truly variadic, restructure so the hint is Tuple[Any, ...] handled by the VAR_POSITIONAL path instead of a list
3. Print the expected tuple_constraint vs actual hint from the message and align arities
4. Use Any elements if the exact per-element types are unknown: Tuple[Any, Any, Any]

Example fix

// before
with_input_types(List[int], int)
def f(points, n): ...
// after
from apache_beam.typehints import Tuple
with_input_types(Tuple[int, int, int], int)
def f(points, n): ...

from apache_beam import typehints
def check_tuple_hint(hint, n):
  expected = typehints.Tuple[[typehints.Any] * n]
  return typehints.is_consistent_with(hint, expected)

try:
  getcallargs_forhints(fn, hints)
except TypeCheckError as e:
  log.error('positional hint arity mismatch: %s', e)

When it happens

Trigger: Calling with_input_types / @with_input_types with a list positional argument whose declared hint is not consistent with Tuple[Any]*len(list), e.g. hint=List[int] or int for a fixed-length list arg, then getcallargs_forhints unpacks positional hints.

Common situations: Annotating *args-using functions where the hint was written for a homogeneous variable-length tuple but the unpacker needs fixed arity; copy-pasted hints between functions with different arity.

Understand the failure class

Background: Type mismatch errors: IllegalArgumentException, TypeError and type guards across 150 open-source libraries — this error's family across 150 libraries.

Related errors

• According to type-hint expected
• All functions for a Combine PTransform must accept a single…
• Combiner input type must be specified positionally.
• Could not determine schema for type hints
• Dict type-constraint violated. All passed instances must be…

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

Appendix: source

Thrown at sdks/python/apache_beam/typehints/decorators.py:702

  Tuple[Tuple[Int, Any], float] when applied to the type hints
  {a: int, b: Any, c: float}.
  """
  if isinstance(arg, list):
    return typehints.Tuple[[_positional_arg_hints(a, hints) for a in arg]]
  return hints.get(arg, typehints.Any)


def _unpack_positional_arg_hints(arg, hint):
  """Unpacks the given hint according to the nested structure of arg.

  For example, if arg is [[a, b], c] and hint is Tuple[Any, int], then
  this function would return ((Any, Any), int) so it can be used in conjunction
  with inspect.getcallargs.
  """
  if isinstance(arg, list):
    tuple_constraint = typehints.Tuple[[typehints.Any] * len(arg)]
    if not typehints.is_consistent_with(hint, tuple_constraint):
      raise TypeCheckError(
          'Bad tuple arguments for %s: expected %s, got %s' %
          (arg, tuple_constraint, hint))
    if isinstance(hint, typehints.TupleConstraint):
      return tuple(
          _unpack_positional_arg_hints(a, t)
          for a, t in zip(arg, hint.tuple_types))
    return (typehints.Any, ) * len(arg)
  return hint


def _normalize_var_positional_hint(hint):
  """Converts a var_positional hint into Tuple[Union[<types>], ...] form.

  Args:
    hint: (tuple) Should be either a tuple of one or more types, or a single
      Tuple[<type>, ...].

  Raises:

View on GitHub (pinned to 12126d8942)