Do these 3 things before closing this tab:
1Clear out junk files and repair common Windows errors2Fix the driver behind crashes, sound loss and screen glitches3Repair Windows errors before they cause bigger problemsA ToolResult ordering error means the message history your application sends to Amazon Bedrock breaks the tool-use cycle. The model asked for a tool, but the next request does not answer that request where the API expects it. In most cases the fix is to keep the assistant’s tool-use turn intact and return each result in a user-role message that carries the matching toolUseId.
Why the order matters in client-side tool use
AWS documents tool calling on Bedrock as an application-managed loop. The Client-side tool use guide states: “If you use the Responses API, Chat Completions API, Converse API, or InvokeModel API to send the request, then the model uses client-side tool calling.” In other words, the model only requests a tool. Your code runs the tool, and your code must send the result back before the model can continue.
As an Amazon Associate I earn from qualifying purchases.
The loop has five steps:
- Send the request with your tool configuration.
- Receive an assistant message containing a tool-use request. Store that message exactly as returned.
- Execute the tool in your application.
- Append a user-role message containing a tool result whose
toolUseIdmatches the request. - Call Converse again with the full history, including the assistant message from step 2.
If any link in that chain is missing, reordered, or rewritten, Bedrock receives a history in which a tool request has no valid answer in the expected position.
The message sequence Bedrock expects
The required pattern is an assistant message with a tool-use block, followed immediately by a user message with the matching tool-result block. The table below shows the three messages involved in a single tool call and the most common ways each one goes wrong.
#1 Best Overall
| Message | Role | Must contain | Typical way it breaks |
|---|---|---|---|
| Tool request | assistant | A toolUse block with toolUseId, name, and input |
Saved as plain text, or dropped when the history is stored and reloaded |
| Tool result | user | A toolResult block with the same toolUseId |
Sent with the wrong role, placed after another user turn, or omitted |
| Final answer | assistant | Text generated after the result is appended | Generated before the result exists, or inserted between the request and its result |
AWS’s tool-use code example follows this pattern: it collects the tool results and adds them as a user-role message before continuing the conversation.
Common causes of the error
A wrapper or framework rewrites the history
Application frameworks often keep their own conversation objects and convert them into Bedrock message arrays just before the call. A conversion step can merge consecutive messages, reorder them, or convert tool events into plain text. Any of these changes can separate a request from its result. Your own code may look correct while the array sent to Bedrock is not.
Rank #2
- Used Book in Good Condition
Stored history loses the assistant tool-use turn
Many applications save only the user prompt and the final assistant text to a database or session store. On the next request, the saved history contains a tool result with no tool request in front of it. The fix is to persist every assistant message as returned, including content blocks of the tool-use type, not only the text you display to users.
The toolUseId is copied incorrectly
Each tool result must echo the toolUseId from its matching request. Errors appear when an application generates its own identifier, reuses an identifier from a previous turn, or truncates or re-serializes the value. Compare the identifiers one to one; do not match them by tool name, because one turn can request the same tool several times.
Multiple tool requests are answered piecemeal
The model can request more than one tool in a single assistant response. If your code sends a user message for the first result, then waits and sends another for the second, the history no longer matches the single response that requested both. Follow the pattern in AWS’s example: execute the requested tools, collect all results, and submit them together in one user message.
Trimming or retries cut into a pair
Context-window trimming, summarization, and retry logic can remove an older message while keeping its partner. A tool result that survives without its tool request is a common result of trimming by message count. When you trim, remove whole tool-use and tool-result pairs, never one side of a pair.
Troubleshooting sequence
- Log the serialized
messagesarray immediately before the Converse call. Do not rely on the framework’s internal objects, which may differ from what is sent. - Find the most recent assistant message containing a tool-use block. Confirm the next message has the user role and contains the tool results.
- Match each
toolUseIdin the request to exactly onetoolResultin the following message. Missing, duplicated, or extra identifiers are all failure points. - If the assistant response requested several tools, confirm that all results sit in that one user message.
- Check every step that edits history, including trimming, summarization, and saved-session reload, and confirm it keeps each pair together.
- Confirm the request shape matches the Converse API and the model you are calling. AWS’s Inference using Converse API page describes the request configuration, and it notes that tool use is supported for supported message-capable models. Details can vary by model and request path, so check the model in use.
Expected message shape
The following sample shows a valid three-message history for one tool call. The IDs are illustrative; in your application, use the identifier returned by the model.
{
"messages": [
{"role": "user", "content": [{"text": "What is the weather in Seattle?"}]},
{"role": "assistant", "content": [{"toolUse": {"toolUseId": "tooluse_example01", "name": "get_weather", "input": {"city": "Seattle"}}}]},
{"role": "user", "content": [{"toolResult": {"toolUseId": "tooluse_example01", "content": [{"text": "{"tempC": 14}"}]}}]}
]
}If your serialized history differs from this shape at the point where the error occurs, that difference is the place to start.
Best Value
What the error does and does not tell you
The AWS documentation establishes the client-side flow and the matching-identifier requirement. It does not define one canonical error string that applies across every SDK, framework, and model, and it does not publish a framework-specific diagnosis. Treat the causes above as hypotheses to confirm from the serialized request and the exact exception your client returns.
Start with the request log. A correctly ordered history that still fails usually points to a model or request-path detail, and the Converse documentation and the model’s own configuration are the next places to verify.
Quick Recap
Product prices and availability are accurate as of the date/time indicated and are subject to change. Any price and availability information displayed on Amazon at the time of purchase will apply.
Recommended Free Tools
