langchain-ai/langgraph · error · TypeError

Tool {name} returned unexpected type: {type}

Error message

Tool {name} returned unexpected type: {type}

What it means

Error "Tool {name} returned unexpected type: {type}" thrown in langchain-ai/langgraph.

Source

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

        tool_call: ToolCall,
        input_type: Literal["list", "dict", "tool_calls"],
    ) -> ToolMessage | Command | list[Command | ToolMessage]:
        """Validate and normalize a tool's raw return value."""
        if isinstance(response, Command):
            return self._validate_tool_command(response, tool_call, input_type)
        if isinstance(response, ToolMessage):
            response.content = cast("str | list", msg_content_output(response.content))
            return response
        if isinstance(response, list):
            if all(isinstance(r, (Command, ToolMessage)) for r in response):
                return self._validate_tool_command_list(response, tool_call, input_type)
            msg = (
                f"Tool {tool_call['name']} returned a list with invalid element "
                "types: expected all Command or ToolMessage"
            )
            raise TypeError(msg)
        msg = f"Tool {tool_call['name']} returned unexpected type: {type(response)}"
        raise TypeError(msg)

    def _validate_tool_command_list(
        self,
        response: list[Command | ToolMessage],
        tool_call: ToolCall,
        input_type: Literal["list", "dict", "tool_calls"],
    ) -> list[Command | ToolMessage]:
        """Validate a list of Command/ToolMessage returned by a single tool call.

        Requires exactly one terminating ToolMessage (matching the outer tool_call_id)
        across the list — either as a top-level element or nested in a
        Command.update["messages"].
        """
        expected_id = tool_call["id"]

        terminator_count = 0
        for item in response:
            if isinstance(item, ToolMessage):

View on GitHub (pinned to 38031739e5)

When it happens

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