apache/beam · error · TypeError

An Option type-hint only accepts a single type parameter.

Error message

An Option type-hint only accepts a single type parameter.

What it means

OptionalHint.__getitem__ raises TypeError('An Option type-hint only accepts a single type parameter.') when Optional[...] is subscripted with a sequence of multiple types. Beam's Optional[X] proxies to Union[X, type(None)] and therefore only accepts exactly one inner type.

Solutions

1. Nest the union inside a single parameter: Optional[Union[int, str]].
2. Use Union[int, str, type(None)] directly if you prefer an explicit union with None.
3. Verify only one type argument is passed when constructing Optional hints.
4. Fix hint-building code to wrap multiple types in Union before applying Optional.

Example fix

# before
Optional[int, str]
# after
Optional[Union[int, str]]

def make_optional(ts):
    if isinstance(ts, (list, tuple)):
        return Optional[Union[tuple(ts)]] if len(ts) > 1 else Optional[ts[0]]
    return Optional[ts]

def is_single_type(x):
    return not isinstance(x, (list, tuple))

try:
    hint = Optional[py_type]
except TypeError as e:
    if 'only accepts a single type' in str(e):
        hint = Optional[Union[tuple(py_type)]]
    else:
        raise

When it happens

Trigger: Writing Optional[int, str] or Optional[List[int], Dict[str, int]] — passing a Sequence to the Optional hint factory instead of one type.

Common situations: Developers assuming Optional behaves like Union (as typing.Optional[X, Y] would error in typing too); mistakenly trying to express 'optional union' as Optional[A, B]; copy-paste from Union definitions.

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

• bad type
• batch type must be List[T] for element type T
• batch type must be np.ndarray or…
• Cannot create Union without a sequence of types.
• hint type-constraint violated. The type of element # in the…

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

Appendix: source

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

      except (TypeError, KeyError):
        # Not a union of compatible schema types.
        pass

    return self.UnionConstraint(params)


UnionConstraint = UnionHint.UnionConstraint


class OptionalHint(UnionHint):
  """An Option type-hint. Optional[X] accepts instances of X or None.

  The Optional[X] factory function proxies to Union[X, type(None)]
  """
  def __getitem__(self, py_type):
    # A single type must have been passed.
    if isinstance(py_type, abc.Sequence):
      raise TypeError(
          'An Option type-hint only accepts a single type '
          'parameter.')

    return Union[py_type, type(None)]


def is_nullable(typehint):
  return (
      isinstance(typehint, UnionConstraint) and
      typehint.contains_type(type(None)) and
      len(list(typehint.inner_types())) == 2)


def get_concrete_type_from_nullable(typehint):
  if is_nullable(typehint):
    for inner_type in typehint.inner_types():
      if not type(None) == inner_type:
        return inner_type

View on GitHub (pinned to 12126d8942)