Claude 400: Fix tool_use Without a Matching tool_result

A Claude error saying that tool_use has no matching tool_result usually points to a broken tool conversation, not a prompt that needs to be reworded. In the native Messages API, the assistant calls a client tool and the next user message returns the result with the matching ID. Check that relationship before retrying the same request.

This guide covers that specific error family in custom integrations and clients such as OpenCode. It does not mean every OpenCode HTTP 400 has this cause. The rules below follow Claude’s tool-call handling documentation, checked September 14, 2026. The examples are synthetic message fragments, not traces of a live API test.

Find the unmatched ID first

Read the complete error message and locate the referenced tool-use ID in the previous assistant message. Then inspect the following user message. Its tool_result.tool_use_id must refer to that exact ID; the name of the tool is not a substitute for the identifier.

In the native Claude protocol, a tool result is a content block inside a user message. There is no native role: "tool" in this message shape. If your adapter also supports another provider’s format, ensure it translates the roles and fields instead of forwarding them unchanged.

A minimal valid message fragment

This JSON shows only the relevant messages. A full request also needs the selected model, tool definition, token limit and the rest of the conversation. The demonstration result is invented for the example and must not be used as a substitute for executing a real tool.

[
  {
    "role": "assistant",
    "content": [
      {"type": "tool_use", "id": "toolu_demo", "name": "lookup", "input": {"key": "demo"}}
    ]
  },
  {
    "role": "user",
    "content": [
      {"type": "tool_result", "tool_use_id": "toolu_demo", "content": "demo result"}
    ]
  }
]

Do not recreate the assistant message from the text displayed in a chat window. Save the complete structured content returned by the API. Other blocks may need to remain in the conversation, including thinking data when the model and workflow require it. Signature validation is a different problem, covered in the Claude thinking-signature guide.

Parallel calls must return a complete set of results

If one assistant message asks for two client tools, collect both results and put them into the immediately following user message. Do not send one result, insert another assistant turn, and then attempt to return the second result to the original call. Place any permitted explanatory user text after the result blocks.

The official troubleshooting guide also describes mixed server-tool workflows. If the same round still has an unfinished server tool, the user message should contain only the client tool results, and the request should preserve the tools array. Do not generalize a minimal client-only example into every server-tool workflow.

Handle real tool failures without inventing success

A failed lookup or command can still have a correctly paired tool result. Return the same ID with is_error: true and an accurate error description when that is the documented client-tool pattern. The protocol relationship and the success of the underlying operation are separate checks.

If the client was interrupted, first determine whether the tool actually ran. A timeout in the interface does not prove that a file write, deployment or external request failed to happen. Inspect the operation’s state before repeating anything with side effects. Do not manufacture a successful result to satisfy the validator, and do not automatically execute a consequential tool twice.

For development, reproduce the sequence with a harmless lookup in a disposable session. A read-only example can reveal the pairing failure without risking another write or transaction. Capture the client version and the message immediately before and after the interruption.

Recover a damaged session carefully

Preserve a local copy of the relevant history before trying a repair. If the original result is available, restore the correctly paired message using the client’s supported recovery mechanism. If the history cannot be repaired safely, create a new session with a concise summary of verified work and pending actions, while retaining the old session for reference.

Deleting arbitrary tool blocks can change what the model believes happened. Deleting all conversation files is therefore not a default fix. When filing an issue, provide a small redacted sequence with the roles, content types and matching IDs. Remove API keys, private tool arguments and sensitive results.

A client upgrade may be worth checking against its release notes, but this article does not identify one version that fixes every case. Historical issues establish that a failure occurred in a particular configuration; they do not prove the same bug remains in the latest release.

Why retrying alone does not solve it

The API validates the conversation structure before continuing the model turn. Sending the same unmatched sequence again leaves the structural problem unchanged. That is a conclusion from the protocol rules, not a measured claim about every client’s retry implementation.

An HTTP 429 or an overloaded service calls for a different investigation. Check the actual status and error body before applying this guide. For other access errors, use the model-not-found diagnostic; it addresses a different protocol and should not be confused with Claude tool-message pairing.

Frequently asked questions

Can a tool return an error and still satisfy the pairing requirement?

Yes. A truthful error result can match the original tool-use ID. Successful execution is not required to represent the failure correctly in the next message.

Should I use role tool with the native Claude API?

No. Native client tool results are user-message content blocks. An OpenAI-compatible adapter may expose another shape, so follow the protocol of the endpoint actually receiving the request.

Is starting a new session a complete fix?

It can isolate damaged history, but it does not repair an adapter that keeps dropping results. Check the serializer or client path that created the broken sequence before relying on the new session.