{"record":{"id":"48f73db1a728b6e0","repo":"apache/beam","slug":"s-must-be-a-non-sequence-a-type-or-a-typeconstraint-s-is-an","errorCode":null,"errorMessage":"%s must be a non-sequence, a type, or a TypeConstraint. %s is an instance of %s.","messagePattern":"(.+?) must be a non-sequence, a type, or a TypeConstraint\\. (.+?) is an instance of (.+?)\\.","errorType":"validation","errorClass":"TypeError","httpStatus":null,"severity":"error","filePath":"sdks/python/apache_beam/typehints/typehints.py","lineNumber":399,"sourceCode":"    error_msg_prefix (:class:`str`): A string prefix used to format an error\n      message in the case of an exception.\n\n  Raises:\n    TypeError: If the passed **type_param** is not a valid type\n      parameter for a :class:`CompositeTypeHint`.\n  \"\"\"\n  # Must either be a TypeConstraint instance or a basic Python type.\n  possible_classes = [type, TypeConstraint]\n  is_not_type_constraint = (\n      not is_typing_generic(type_param) and\n      not isinstance(type_param, tuple(possible_classes)) and\n      type_param is not None and\n      getattr(type_param, '__module__', None) != 'typing')\n  if isinstance(type_param, types.UnionType):\n    is_not_type_constraint = False\n\n  if is_not_type_constraint:\n    raise TypeError(\n        '%s must be a non-sequence, a type, or a TypeConstraint. %s'\n        ' is an instance of %s.' %\n        (error_msg_prefix, type_param, type_param.__class__.__name__))\n\n\ndef check_constraint(type_constraint, object_instance):\n  \"\"\"Determine if the passed type instance satisfies the TypeConstraint.\n\n  When examining a candidate type for constraint satisfaction in\n  'type_check', all CompositeTypeHint's eventually call this function. This\n  function may end up being called recursively if the hinted type of a\n  CompositeTypeHint is another CompositeTypeHint.\n\n  Args:\n    type_constraint: An instance of a TypeConstraint or a built-in Python type.\n    object_instance: An object instance.\n\n  Raises:","sourceCodeStart":381,"sourceCodeEnd":417,"githubUrl":"https://github.com/apache/beam/blob/12126d8942aaf848030c478b4c6a28c6af861c66/sdks/python/apache_beam/typehints/typehints.py#L381-L417","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","solutions":["Pass classes/types or TypeConstraint instances as parameters, not instances (List[int], not List[int()]).","Verify each element of a sequence of type params is a type or hint, e.g. Tuple[str, int].","If using typing-module generics, keep them consistent (don't mix typing.Union instances with raw values).","Print/type-check the offending parameter shown in the message to find where the instance leaked in."],"exampleFix":"# before\nbeam.Map(fn).with_output_types(List[int(42)])\n# after\nbeam.Map(fn).with_output_types(List[int])","handlingStrategy":"type-guard","validationCode":"import typing, types\nfrom apache_beam.typehints import TypeConstraint\ndef is_valid_hint_param(p):\n    return isinstance(p, type) or isinstance(p, TypeConstraint) or p is None \\\n        or getattr(p, '__module__', None) == 'typing' or isinstance(p, types.UnionType)","typeGuard":"def is_type_like(x):\n    return isinstance(x, type)","tryCatchPattern":"try:\n    t = with_output_types(*params)\nexcept TypeError as e:\n    if 'must be a non-sequence, a type, or a TypeConstraint' in str(e):\n        logger.error('bad type param: %s', e)\n    raise","preventionTips":["Never pass instances where types are expected in hint subscripts","Keep hint construction declarative (literals), not computed from runtime values","Lint for patterns like Hint[expr()] in pipeline code"],"tags":["python","apache-beam","typehints","typeerror"],"backgroundTag":"invalid-argument-value","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"}