{"record":{"id":"7ce78f3fd3c83f3a","repo":"apache/beam","slug":"unexpected-var-positional-value-s","errorCode":null,"errorMessage":"Unexpected VAR_POSITIONAL value: %s","messagePattern":"Unexpected VAR_POSITIONAL value: (.+?)","errorType":"validation","errorClass":"TypeCheckError","httpStatus":null,"severity":"error","filePath":"sdks/python/apache_beam/typehints/decorators.py","lineNumber":724,"sourceCode":"      return tuple(\n          _unpack_positional_arg_hints(a, t)\n          for a, t in zip(arg, hint.tuple_types))\n    return (typehints.Any, ) * len(arg)\n  return hint\n\n\ndef _normalize_var_positional_hint(hint):\n  \"\"\"Converts a var_positional hint into Tuple[Union[<types>], ...] form.\n\n  Args:\n    hint: (tuple) Should be either a tuple of one or more types, or a single\n      Tuple[<type>, ...].\n\n  Raises:\n    TypeCheckError if hint does not have the right form.\n  \"\"\"\n  if not hint or type(hint) != tuple:\n    raise TypeCheckError('Unexpected VAR_POSITIONAL value: %s' % hint)\n\n  if len(hint) == 1 and isinstance(hint[0], typehints.TupleSequenceConstraint):\n    # Example: tuple(Tuple[Any, ...]) -> Tuple[Any, ...]\n    return hint[0]\n  else:\n    # Example: tuple(int, str) -> Tuple[Union[int, str], ...]\n    return typehints.Tuple[typehints.Union[hint], ...]\n\n\ndef _normalize_var_keyword_hint(hint, arg_name):\n  \"\"\"Converts a var_keyword hint into Dict[<key type>, <value type>] form.\n\n  Args:\n    hint: (dict) Should either contain a pair (arg_name,\n      Dict[<key type>, <value type>]), or one or more possible types for the\n      value.\n    arg_name: (str) The keyword receiving this hint.\n","sourceCodeStart":706,"sourceCodeEnd":742,"githubUrl":"https://github.com/apache/beam/blob/12126d8942aaf848030c478b4c6a28c6af861c66/sdks/python/apache_beam/typehints/decorators.py#L706-L742","documentation":"_normalize_var_positional_hint normalizes the hint recorded for a *args parameter into a variadic Tuple[<type>, ...]. It expects a non-empty tuple of hint constraints; anything else (None, empty tuple, a list, a single non-tuple constraint) raises TypeCheckError.","triggerScenarios":"Calling getcallargs_forhints on a function with a *args parameter whose recorded hint is not a tuple of constraints — e.g. hint stored as a single type int, an empty tuple, or None because the hint registry was populated incorrectly.","commonSituations":"Manually constructing IOTypeHints and passing a bare type instead of (type,) for VAR_POSITIONAL; bug in custom hint plumbing that forgets to wrap the variadic hint in a tuple; older serialized hints migrated across Beam versions.","solutions":["Wrap the *args hint in a one-element tuple: (Tuple[int, ...],) so the normalization branch len(hint)==1 with TupleSequenceConstraint applies","For mixed *args use tuple(int, str) form — i.e. pass (int, str) as the hint tuple","Inspect how the hint was attached (with_input_types vs TypeHintVisitor) and use the decorator API instead of hand-built structures","Upgrade Beam if hints were produced by an older serialization path"],"exampleFix":"// before\nhints = IOTypeHints(..., var_positional_arg=int)\n// after\nhints = IOTypeHints(..., var_positional_arg=(int,))  # or (Tuple[int, ...],)","handlingStrategy":"validation","validationCode":"def is_valid_var_positional(h):\n  return isinstance(h, tuple) and len(h) >= 1","typeGuard":null,"tryCatchPattern":"try:\n  args = getcallargs_forhints(fn, hints)\nexcept TypeCheckError as e:\n  log.error('bad VAR_POSITIONAL hint: %s', e)","preventionTips":["Always store *args hints as a tuple of constraints, e.g. (int,)","Prefer (Tuple[T, ...],) for homogeneous *args","Build hints via decorators, not raw IOTypeHints fields"],"tags":["python","type-hints","apache-beam"],"backgroundTag":"invalid-argument-format","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"}