apache/beam · error · TypeError

Ellipsis can only be used to type-hint an arbitrary length…

Error message

Ellipsis can only be used to type-hint an arbitrary length tuple of containing a single type: Tuple[A, ...].

What it means

Raised by Tuple.__getitem__ when Ellipsis appears anywhere but as the sole second parameter of a 2-element parameter list. Ellipsis is only valid in the exact form Tuple[A, ...] for homogeneous arbitrary-length tuples.

Solutions

Use Tuple[A, ...] exactly: one type then Ellipsis
For heterogeneous trailing values, enumerate every type explicitly, e.g. Tuple[int, str, str]
For mixed arbitrary content use Tuple[Any, ...] or List[Any]

Example fix

# before
Tuple[int, str, ...]
# after
Tuple[int, str, str]  # or Tuple[Any, ...]

Defensive patterns

Strategy: type-guard

Prevention

Only use Ellipsis in the exact Tuple[A, ...] form
Prefer explicit arities for heterogeneous tuples
Reach for Tuple[Any, ...] when content is genuinely arbitrary

When it happens

Trigger: Tuple[int, str, ...]; Tuple[...] or Ellipsis not last; more than one Ellipsis.

Common situations: Developers assuming Ellipsis means 'more of anything' at the end, mimicking typing.Tuple[int, ...] misuse or mixing heterogeneous and varargs forms.

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

Appendix: source

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

      return bindings

    def bind_type_variables(self, bindings):
      bound_tuple_types = tuple(
          bind_type_variables(t, bindings) for t in self.tuple_types)
      if bound_tuple_types == self.tuple_types:
        return self
      return Tuple[bound_tuple_types]

  def __getitem__(self, type_params):
    ellipsis = False

    if not isinstance(type_params, abc.Iterable):
      # Special case for hinting tuples with arity-1.
      type_params = (type_params, )

    if type_params and type_params[-1] == Ellipsis:
      if len(type_params) != 2:
        raise TypeError(
            'Ellipsis can only be used to type-hint an arbitrary '
            'length tuple of containing a single type: '
            'Tuple[A, ...].')
      # Tuple[A, ...] indicates an arbitary length homogeneous tuple.
      type_params = type_params[:1]
      ellipsis = True

    for t in type_params:
      validate_composite_type_param(
          t, error_msg_prefix='All parameters to a Tuple hint')

    if ellipsis:
      return self.TupleSequenceConstraint(type_params[0])
    return self.TupleConstraint(type_params)


TupleConstraint = TupleHint.TupleConstraint
TupleSequenceConstraint = TupleHint.TupleSequenceConstraint

View on GitHub (pinned to 12126d8942)