langchain-ai/langgraph · error · ValueError

Tool {name} returned a list with {count} messages bound to t

Error message

Tool {name} returned a list with {count} messages bound to tool_call_id '{id}'; expected exactly one terminating ToolMessage.

What it means

Error "Tool {name} returned a list with {count} messages bound to tool_call_id '{id}'; expected exactly one terminating ToolMessage." thrown in langchain-ai/langgraph.

Source

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

        expected_id = tool_call["id"]

        terminator_count = 0
        for item in response:
            if isinstance(item, ToolMessage):
                if item.tool_call_id == expected_id:
                    terminator_count += 1
            elif isinstance(item, Command) and isinstance(item.update, dict):
                for msg in item.update.get(self._messages_key, []):
                    if isinstance(msg, ToolMessage) and msg.tool_call_id == expected_id:
                        terminator_count += 1

        if terminator_count != 1:
            msg = (
                f"Tool {tool_call['name']} returned a list with "
                f"{terminator_count} messages bound to tool_call_id "
                f"{expected_id!r}; expected exactly one terminating ToolMessage."
            )
            raise ValueError(msg)

        # Per-Command normalization still runs, but the list-level count above
        # already guarantees exactly one terminator, so individual Commands may
        # lack one.
        validated: list[Command | ToolMessage] = []
        for item in response:
            if isinstance(item, Command):
                validated.append(
                    self._validate_tool_command(
                        item, tool_call, input_type, require_terminator=False
                    )
                )
            else:
                item.content = cast("str | list", msg_content_output(item.content))
                validated.append(item)
        return validated

    def _validate_tool_command(

View on GitHub (pinned to 38031739e5)

When it happens

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