apache/beam · error · ValueError

'returns' accepts only a single positional argument. In…

Error message

'returns' accepts only a single positional argument. In order to specify multiple return types, use the 'Tuple' type-hint.

What it means

The @with_output_types decorator accepts exactly one positional return type hint. Passing multiple positional arguments (e.g. @with_output_types(int, str)) raises this ValueError, telling the user to encode multiple return types as a single Tuple hint instead.

Solutions

Combine into a Tuple: @with_output_types(Tuple[int, str])
If one of the returns is a tagged output, use output_types=... / TaggedOutput[Literal['tag'], T] in kwargs instead
Keep native typing syntax (tuple[int, str]) which convert_to_beam_type translates automatically
Count positional args before decorating; only the first is consumed as the return type

Example fix

// before
@with_output_types(int, str)
def f(x): ...
// after
from apache_beam.typehints import Tuple
@with_output_types(Tuple[int, str])
def f(x): ...

Defensive patterns

Strategy: validation

Validate before calling

import inspect
sig = inspect.signature(with_output_types)
assert all(p.kind == p.POSITIONAL_OR_KEYWORD or p.default is not p.empty for p in sig.parameters.values())
# count positional args before decorating
def check_returns_args(n): return n <= 1

Try / catch

try:
  decorated = with_output_types(*ret_types)
except ValueError as e:
  if 'single positional argument' in str(e):
    decorated = with_output_types(Tuple[tuple(ret_types)])

Prevention

Never pass more than one positional return type to @with_output_types
Use Tuple[...] to express multiple return types
Use kwargs (output_types=) for tagged outputs

When it happens

Trigger: @with_output_types(int, str) or @with_output_types(int, Dict[str, int]) — two or more positional return_type_hint args — at decoration time.

Common situations: Developers assuming the decorator takes one type per return value, mirroring input-type decorators that accept per-argument hints; porting from frameworks where multi-returns are comma-separated.

Understand the failure class

Background: "missing required argument" and "the following required arguments were not provided": what required-argument errors mean and how to fix them — this error's family across 20 libraries.

Related errors

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

Appendix: source

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

      created by 'indexing' a
      :class:`~apache_beam.typehints.typehints.CompositeTypeHint`.
    **tagged_type_hints: Type hints for tagged outputs. Each keyword argument
      specifies the type for a tagged output, e.g., ``errors=str``.


  Raises:
    :class:`ValueError`: If the length of **return_type_hint** is greater
      than ``1``. Or if the inner wrapper function isn't passed a function
      object.
    :class:`TypeCheckError`: If the **return_type_hint** object is
      in invalid type-hint.

  Returns:
    The original function decorated such that it enforces type-hint constraints
    for all return values.
  """
  if len(return_type_hint) != 1:
    raise ValueError(
        "'returns' accepts only a single positional argument. In "
        "order to specify multiple return types, use the 'Tuple' "
        "type-hint.")

  return_type_hint = native_type_compatibility.convert_to_beam_type(
      return_type_hint[0])
  validate_composite_type_param(
      return_type_hint, error_msg_prefix='All type hint arguments')

  converted_tag_hints = {}
  for tag, hint in tagged_type_hints.items():
    converted_hint = native_type_compatibility.convert_to_beam_type(hint)
    validate_composite_type_param(
        converted_hint, 'Tagged output type hint for %r' % tag)
    converted_tag_hints[tag] = converted_hint

  def annotate_output_types(f):
    th = getattr(f, '_type_hints', IOTypeHints.empty())

View on GitHub (pinned to 12126d8942)