langchain-ai/langgraph · error · ValueError

Got unexpected type of `handle_tool_error`. Expected bool, s

Error message

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

What it means

Error "Got unexpected type of `handle_tool_error`. Expected bool, str or callable. Received: {flag}" thrown in langchain-ai/langgraph.

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)

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.