langchain-ai/langgraph · error · ValueError

All types in the error handler error annotation must be Exce

Error message

All types in the error handler error annotation must be Exception types. For example, `def custom_handler(e: Union[ValueError, TypeError])`. Got '{annotation}' instead.

What it means

Error "All types in the error handler error annotation must be Exception types. For example, `def custom_handler(e: Union[ValueError, TypeError])`. Got '{annotation}' instead." thrown in langchain-ai/langgraph.

Source

Thrown at libs/prebuilt/langgraph/prebuilt/tool_node.py:490

        if params[0].name in ["self", "cls"] and len(params) == 2:
            first_param = params[1]
        else:
            first_param = params[0]

        type_hints = get_type_hints(handler)
        if first_param.name in type_hints:
            origin = get_origin(first_param.annotation)
            if origin in [Union, UnionType]:
                args = get_args(first_param.annotation)
                if all(issubclass(arg, Exception) for arg in args):
                    return tuple(args)
                msg = (
                    "All types in the error handler error annotation must be "
                    "Exception types. For example, "
                    "`def custom_handler(e: Union[ValueError, TypeError])`. "
                    f"Got '{first_param.annotation}' instead."
                )
                raise ValueError(msg)

            exception_type = type_hints[first_param.name]
            if Exception in exception_type.__mro__:
                return (exception_type,)
            msg = (
                f"Arbitrary types are not supported in the error handler "
                f"signature. Please annotate the error with either a "
                f"specific Exception type or a union of Exception types. "
                "For example, `def custom_handler(e: ValueError)` or "
                "`def custom_handler(e: Union[ValueError, TypeError])`. "
                f"Got '{exception_type}' instead."
            )
            raise ValueError(msg)

    # If no type information is available, return (Exception,)
    # for backwards compatibility.
    return (Exception,)

View on GitHub (pinned to 38031739e5)

When it happens

Trigger: Thrown at libs/prebuilt/langgraph/prebuilt/tool_node.py:490 when the library encounters an invalid state.

Common situations: See trigger scenarios.

AI-assisted analysis of langchain-ai/langgraph@38031739e5 (2026-08-26). Data as JSON: /api/errors/871427ece6fd816e. Report an issue: GitHub.