apache/beam · error · TypeError

must be a non-sequence, a type, or a TypeConstraint. is an…

Error message

%s must be a non-sequence, a type, or a TypeConstraint. %s is an instance of %s.

What it means

validate_composite_type_param raises TypeError when a parameter passed to a composite type-hint constructor (Union[...], Tuple[...], etc.) is not a bare type, a TypeConstraint, None, or a typing-module construct. Beam validates every type parameter and rejects arbitrary objects/instances used as type parameters.

Solutions

1. Pass classes/types or TypeConstraint instances as parameters, not instances (List[int], not List[int()]).
2. Verify each element of a sequence of type params is a type or hint, e.g. Tuple[str, int].
3. If using typing-module generics, keep them consistent (don't mix typing.Union instances with raw values).
4. Print/type-check the offending parameter shown in the message to find where the instance leaked in.

Example fix

# before
beam.Map(fn).with_output_types(List[int(42)])
# after
beam.Map(fn).with_output_types(List[int])

import typing, types
from apache_beam.typehints import TypeConstraint
def is_valid_hint_param(p):
    return isinstance(p, type) or isinstance(p, TypeConstraint) or p is None \
        or getattr(p, '__module__', None) == 'typing' or isinstance(p, types.UnionType)

def is_type_like(x):
    return isinstance(x, type)

try:
    t = with_output_types(*params)
except TypeError as e:
    if 'must be a non-sequence, a type, or a TypeConstraint' in str(e):
        logger.error('bad type param: %s', e)
    raise

When it happens

Trigger: Calling with_input_types/with_output_types or subscripting a hint with an instance instead of a type, e.g. List[3] or Union[my_instance], or a sequence element that isn't a valid type param; __getitem__ calls validate_composite_type_param per parameter.

Common situations: Accidentally passing an instantiated generic (List[int()]), passing a beam type-hint object where a typing construct was expected, mixing typing.List with beam's List incorrectly, typos leaving a variable holding an instance rather than a class.

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

• A context manager constructor (not a fully constructed…
• An Option type-hint only accepts a single type parameter.
• bad type
• batch type must be List[T] for element type T
• batch type must be np.ndarray or…

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

Appendix: source

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

    error_msg_prefix (:class:`str`): A string prefix used to format an error
      message in the case of an exception.

  Raises:
    TypeError: If the passed **type_param** is not a valid type
      parameter for a :class:`CompositeTypeHint`.
  """
  # Must either be a TypeConstraint instance or a basic Python type.
  possible_classes = [type, TypeConstraint]
  is_not_type_constraint = (
      not is_typing_generic(type_param) and
      not isinstance(type_param, tuple(possible_classes)) and
      type_param is not None and
      getattr(type_param, '__module__', None) != 'typing')
  if isinstance(type_param, types.UnionType):
    is_not_type_constraint = False

  if is_not_type_constraint:
    raise TypeError(
        '%s must be a non-sequence, a type, or a TypeConstraint. %s'
        ' is an instance of %s.' %
        (error_msg_prefix, type_param, type_param.__class__.__name__))


def check_constraint(type_constraint, object_instance):
  """Determine if the passed type instance satisfies the TypeConstraint.

  When examining a candidate type for constraint satisfaction in
  'type_check', all CompositeTypeHint's eventually call this function. This
  function may end up being called recursively if the hinted type of a
  CompositeTypeHint is another CompositeTypeHint.

  Args:
    type_constraint: An instance of a TypeConstraint or a built-in Python type.
    object_instance: An object instance.

  Raises:

View on GitHub (pinned to 12126d8942)