langchain-ai/langgraph · error · ValueError

Arbitrary types are not supported in the error handler…

Error message

Arbitrary types are not supported in the error handler signature. Please annotate the error with either a specific Exception type or a union of Exception types. For example, `def custom_handler(e: ValueError)` or `def custom_handler(e: Union[ValueError, TypeError])`. Got '{exception_type}' instead.

What it means

Error "Arbitrary types are not supported in the error handler signature. Please annotate the error with either a specific Exception type or a union of Exception types. For example, `def custom_handler(e: ValueError)` or `def custom_handler(e: Union[ValueError, TypeError])`. Got '{exception_type}' instead." thrown in langchain-ai/langgraph.

Solutions

1. Annotate the error parameter with a concrete Exception type, e.g. `def custom_handler(e: ValueError)`
2. For multiple types use a union of Exception subclasses: `def custom_handler(e: Union[ValueError, TypeError])`
3. Annotate with plain `Exception` to catch all tool errors

When it happens

Trigger: Thrown at libs/prebuilt/langgraph/prebuilt/tool_node.py:503 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/c39a57e8f7894dfe. Report an issue: GitHub.

Appendix: source

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

                    "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,)


def _filter_validation_errors(
    validation_error: ValidationError,
    injected_args: _InjectedArgs | None,
) -> list[ErrorDetails]:
    """Filter validation errors to only include LLM-controlled arguments.

    When a tool invocation fails validation, only errors for arguments that the LLM
    controls should be included in error messages. This ensures the LLM receives
    focused, actionable feedback about parameters it can actually fix. System-injected
    arguments (state, store, runtime) are filtered out since the LLM has no control
    over them.

View on GitHub (pinned to 38031739e5)