langchain-ai/langgraph · error · ValueError

Got unexpected type of `handle_tool_error`. Expected bool…

Error message

Got unexpected type of `handle_tool_error`. Expected bool, str or callable. Received: {flag}

What it means

Guard in the tool-error formatting helper: `handle_tool_error` on a tool or ToolNode must be a bool, a string template, an Exception type/tuple, or a callable. Any other type falls through to this error, meaning the error-handling configuration itself is invalid before any tool even failed.

Solutions

1. Set handle_tool_error to True/False, a static message string, or a callable like `lambda e: f"tool failed: {e}"`
2. Use a tuple of Exception types or a single Exception class to filter which errors are handled

When it happens

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

Appendix: source

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

    !!! note
        The tuple case is handled by the caller through exception type checking,
        not by this function directly.
    """
    if isinstance(flag, (bool, tuple)) or (
        isinstance(flag, type) and issubclass(flag, Exception)
    ):
        content = TOOL_CALL_ERROR_TEMPLATE.format(error=repr(e))
    elif isinstance(flag, str):
        content = flag
    elif callable(flag):
        content = flag(e)  # type: ignore [assignment, call-arg]
    else:
        msg = (
            f"Got unexpected type of `handle_tool_error`. Expected bool, str "
            f"or callable. Received: {flag}"
        )
        raise ValueError(msg)
    return content


def _infer_handled_types(handler: Callable[..., str]) -> tuple[type[Exception], ...]:
    """Infer exception types handled by a custom error handler function.

    This function analyzes the type annotations of a custom error handler to determine
    which exception types it's designed to handle. This enables type-safe error handling
    where only specific exceptions are caught and processed by the handler.

    Args:
        handler: A callable that takes an exception and returns an error message string.
                The first parameter (after self/cls if present) should be type-annotated
                with the exception type(s) to handle.

    Returns:
        A tuple of exception types that the handler can process. Returns (Exception,)
        if no specific type information is available for backward compatibility.

View on GitHub (pinned to 38031739e5)