INVALID_TOOL_RESULTS: every tool call needs exactly one matching ToolMessage

TL;DR: When the model returns tool calls, you must answer each one with exactly one ToolMessage carrying the matching toolcallid. Too few, too many, or orphaned ToolMessages all break the message chain. INVALIDTOOLRESULTS The contract An AIMessage with toolcalls must be followed by exactly one ToolMessage per call, with matching toolcallid values. Count: len(toolcalls) on the AIMessage must equal the number of ToolMessages you append, and every toolcallid must match.

The error

lc_error_code

The fix

1. Too few: the model requested two tool calls, you appended one ToolMessage. The model rejects the incomplete chain.
2. Too many or duplicates: two ToolMessages for the same toolcallid, or an id that matches nothing.
3. Orphaned: a ToolMessage with no preceding AIMessage containing tool calls.
4. Count: len(tool_calls) on the AIMessage must equal the number of ToolMessages you append, and every tool_call_id must match.
5. If you are building the history by hand (custom agent loop), let LangGraph's ToolNode do this instead; it enforces the pairing for you.
6. In JS this is the INVALIDTOOLRESULTS error code on lc_error_code.

When to use this

• You are seeing this exact error message; match the block above, not just part of it.
• The failing call matches the scenario in the title: INVALIDTOOLRESULTS.
• You want the fastest verified fix before digging through logs.

When not to use this

• Your error text differs from the block above; close cousins often have different causes.
• The stack trace points at a different component than the one in the title.
• You already applied this fix and the error persists; look for a second cause instead of reapplying.

Compatibility

• Not pinned to a specific version; follows current INVALIDTOOLRESULTS behavior.

Edge cases

• Rule Never hand-assemble tool result messages unless you have to.

Error catalog entry grounded in the official INVALIDTOOLRESULTS error page, verified 2026-09-26. Error page: https://docs.langchain.com/oss/python/langchain/errors/INVALIDTOOLRESULTS