{"record":{"id":"5973ebe9eb0023ca","repo":"apache/beam","slug":"returns-accepts-only-a-single-positional-argument-in-order","errorCode":null,"errorMessage":"'returns' accepts only a single positional argument. In order to specify multiple return types, use the 'Tuple' type-hint.","messagePattern":"'returns' accepts only a single positional argument\\. In order to specify multiple return types, use the 'Tuple' type-hint\\.","errorType":"validation","errorClass":"ValueError","httpStatus":null,"severity":"error","filePath":"sdks/python/apache_beam/typehints/decorators.py","lineNumber":988,"sourceCode":"      created by 'indexing' a\n      :class:`~apache_beam.typehints.typehints.CompositeTypeHint`.\n    **tagged_type_hints: Type hints for tagged outputs. Each keyword argument\n      specifies the type for a tagged output, e.g., ``errors=str``.\n\n\n  Raises:\n    :class:`ValueError`: If the length of **return_type_hint** is greater\n      than ``1``. Or if the inner wrapper function isn't passed a function\n      object.\n    :class:`TypeCheckError`: If the **return_type_hint** object is\n      in invalid type-hint.\n\n  Returns:\n    The original function decorated such that it enforces type-hint constraints\n    for all return values.\n  \"\"\"\n  if len(return_type_hint) != 1:\n    raise ValueError(\n        \"'returns' accepts only a single positional argument. In \"\n        \"order to specify multiple return types, use the 'Tuple' \"\n        \"type-hint.\")\n\n  return_type_hint = native_type_compatibility.convert_to_beam_type(\n      return_type_hint[0])\n  validate_composite_type_param(\n      return_type_hint, error_msg_prefix='All type hint arguments')\n\n  converted_tag_hints = {}\n  for tag, hint in tagged_type_hints.items():\n    converted_hint = native_type_compatibility.convert_to_beam_type(hint)\n    validate_composite_type_param(\n        converted_hint, 'Tagged output type hint for %r' % tag)\n    converted_tag_hints[tag] = converted_hint\n\n  def annotate_output_types(f):\n    th = getattr(f, '_type_hints', IOTypeHints.empty())","sourceCodeStart":970,"sourceCodeEnd":1006,"githubUrl":"https://github.com/apache/beam/blob/12126d8942aaf848030c478b4c6a28c6af861c66/sdks/python/apache_beam/typehints/decorators.py#L970-L1006","documentation":"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.","triggerScenarios":"@with_output_types(int, str) or @with_output_types(int, Dict[str, int]) — two or more positional return_type_hint args — at decoration time.","commonSituations":"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.","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"],"exampleFix":"// before\n@with_output_types(int, str)\ndef f(x): ...\n// after\nfrom apache_beam.typehints import Tuple\n@with_output_types(Tuple[int, str])\ndef f(x): ...","handlingStrategy":"validation","validationCode":"import inspect\nsig = inspect.signature(with_output_types)\nassert all(p.kind == p.POSITIONAL_OR_KEYWORD or p.default is not p.empty for p in sig.parameters.values())\n# count positional args before decorating\ndef check_returns_args(n): return n <= 1","typeGuard":null,"tryCatchPattern":"try:\n  decorated = with_output_types(*ret_types)\nexcept ValueError as e:\n  if 'single positional argument' in str(e):\n    decorated = with_output_types(Tuple[tuple(ret_types)])","preventionTips":["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"],"tags":["python","type-hints","apache-beam","decorator"],"backgroundTag":"missing-required-argument","analyzedSha":"12126d8942aaf848030c478b4c6a28c6af861c66","analyzedAt":"2026-09-13T01:50:10.254Z","contentChangedAt":"2026-09-13T01:50:10.254Z","schemaVersion":2},"datasetVersion":"2026-09-20T03:17:13.778Z"}