apache/beam · error · ValueError

Unsupported Union with no arguments.

Error message

Unsupported Union with no arguments.

What it means

convert_to_beam_type translates native typing annotations into Beam typehints. A bare typing.Union (used without subscript, i.e. no member types) has no arguments to convert, so Beam raises ValueError 'Unsupported Union with no arguments.' Bare Union is essentially meaningless in an annotation.

Source

Thrown at sdks/python/apache_beam/typehints/native_type_compatibility.py:518

          beam_type=typehints.Mapping),
  ]

  # Find the first matching entry.
  matched_entry = next((entry for entry in type_map if entry.match(typ)), None)
  if not matched_entry:
    # Please add missing type support if you see this message.
    _LOGGER.info('Using Any for unsupported type: %s', typ)
    return typehints.Any

  args = _get_args(typ)
  len_args = len(args)
  if len_args == 0 and len_args != matched_entry.arity:
    arity = matched_entry.arity
    # Handle unsubscripted types.
    if _match_issubclass(typing.Tuple)(typ):
      args = (typehints.TypeVariable('T'), Ellipsis)
    elif _match_is_union(typ):
      raise ValueError('Unsupported Union with no arguments.')
    elif _match_issubclass(typing.Generator)(typ):
      # Assume a simple generator.
      args = (typehints.TypeVariable('T_co'), type(None), type(None))
    elif _match_issubclass(typing.Dict)(typ):
      args = (typehints.TypeVariable('KT'), typehints.TypeVariable('VT'))
    elif (_match_issubclass(typing.Iterator)(typ) or
          _match_is_exactly_iterable(typ)):
      args = (typehints.TypeVariable('T_co'), )
    else:
      args = (typehints.TypeVariable('T'), ) * arity
  elif matched_entry.arity == -1:
    arity = len_args
  # Counters are special dict types that are implicitly parameterized to
  # [T, int], so we fix cases where they only have one argument to match
  # a more traditional dict hint.
  elif len_args == 1 and _safe_issubclass(getattr(typ, '__origin__', typ),
                                          collections.Counter):
    args = (args[0], int)

View on GitHub (pinned to 12126d8942)

Solutions

1. Subscript the union with its member types: Union[int, str] instead of bare Union
2. If any type is acceptable, use typing.Any instead of a bare Union
3. If a default placeholder is needed in generated code, use object or Any rather than typing.Union
4. Run typing.get_type_hints on string annotations so unresolved ForwardRefs don't surface as bare Union

Example fix

// before
@with_output_types(Union)
def f(x): ...
// after
from typing import Union
@with_output_types(Union[int, str])
def f(x): ...

from typing import Union, get_args, Any
def is_subscripted_union(t):
  return t is not Union and (get_args(t) != () or get_origin(t) is not Union)

def is_usable_native_type(t):
  if t is Union:
    return False
  o = get_origin(t)
  return o is not Union or len(get_args(t)) > 0

try:
  beam_hint = convert_to_beam_type(t)
except ValueError as e:
  if 'no arguments' in str(e):
    beam_hint = Any  # treat bare Union as Any

When it happens

Trigger: Writing output_types=Union (unsubscripted) in @with_output_types, from_callable hint extraction, or _extract_tagged_from_type — anywhere a native typing annotation is a plain Union object with len(args)==0 and the union branch of the unsubscripted-type handler is hit.

Common situations: Typos like Union instead of Union[int, str]; using typing.Union itself as a sentinel/default value in generated code or metaprogramming; forgetting subscripts when converting from string annotations via get_type_hints.

Understand the failure class

Background: "Must be a positive integer", "Invalid value", "Unsupported": the invalid-argument-value error family, when a library rejects the value you pass — this error's family across 35 libraries.

Related errors

• First type parameter of TaggedOutput must be Literal['tag_na
• expecting type %s to have arity %d, had arity %d instead
• Unable to deterministically encode '%s' of type '%s', please
• Pipeline type checking is enabled, however no output type-hi
• DoFn {self!r} yields element from both process and process_b

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