Why tool_result could not be submitted Keeps Coming Back, and How to Build a Recovery Handler That Actually Holds

Stopping ordering drift with a strict type

This one only happens if you misunderstand the SDK shape. The pairing rule is non-negotiable: tool_use must sit in an assistant message and its matching tool_result must sit in the very next user message, with nothing else in that user message. Specifically the cadence is:

1. user message
2. assistant message (mixing text and tool_use is fine)
3. user message (tool_result only — no text)
4. assistant message (next response)

It is tempting to bolt a user "comment" onto the tool_result turn as an extra text block. It looks like it works. Then mid-stream resume comes around and the API rejects with could not be submitted. Always make the extra comment a fresh user turn on the next round.

I make this impossible at the type level. The function that builds the tool-result turn refuses anything that is not a tool_result block:

type ToolResultOnlyMessage = {
  role: "user";
  content: Array<{
    type: "tool_result";
    tool_use_id: string;
    content: string;
    is_error?: boolean;
  }>;
};
 
function appendToolResults(
  history: MessageParam[],
  resultMessage: ToolResultOnlyMessage
): MessageParam[] {
  return [...history, resultMessage];
}

Recovering from mid-stream interruptions

The trickiest one. A parallel tool_use block returns five calls; you finish three; the process dies, the network drops, the container restarts. On resume you want to "continue from where you stopped" — but you cannot send three tool_result blocks for five tool_use ids. Every id has to be answered or the whole message is rejected.

The fix is checkpointing. In my implementation I flush state to disk immediately before and after each tool execution.

interface Checkpoint {
  conversationId: string;
  messageIndex: number;       // which assistant turn's tool_use batch
  pendingToolUses: ToolInvocation[];
  executedToolUses: ToolInvocation[];
  lastFlushedAt: number;
}
 
async function executeToolWithCheckpoint(
  cp: Checkpoint,
  inv: ToolInvocation,
  toolFn: (input: unknown) => Promise<string>
): Promise<void> {
  // Flush before execution: if we crash now, we know this one was in flight
  cp.pendingToolUses.push(inv);
  await flushCheckpoint(cp);
 
  try {
    inv.result = await toolFn(inv.input);
  } catch (err) {
    inv.error = err instanceof Error ? err.message : String(err);
    inv.result = `error: ${inv.error}`;
  }
 
  cp.executedToolUses.push(inv);
  await flushCheckpoint(cp);
}
 
/**
 * On resume: pending has every tool_use the assistant emitted, executed
 * has only the ones that finished. Any unfinished entry gets stubbed in
 * as a timeout error so the message array is internally consistent.
 */
async function resumeFromCheckpoint(
  client: Anthropic,
  cp: Checkpoint,
  history: MessageParam[]
): Promise<MessageParam[]> {
  const executedIds = new Set(cp.executedToolUses.map((e) => e.id));
  const missing = cp.pendingToolUses.filter((p) => !executedIds.has(p.id));
 
  for (const m of missing) {
    cp.executedToolUses.push({
      ...m,
      result: "tool execution interrupted by client restart",
      error: "interrupted",
    });
  }
 
  const pendingMap = new Map(cp.pendingToolUses.map((p) => [p.id, p]));
  const executedMap = new Map(cp.executedToolUses.map((e) => [e.id, e]));
  const resultMessage = buildToolResultMessage(pendingMap, executedMap);
 
  return [...history, resultMessage];
}

After shipping this, the once-or-twice-monthly resume failures vanished — three months and counting at zero. The checkpoint I/O is a few KB of JSON flushed locally, so agent latency moved by less than 1ms.

Tiered summarization for oversized tool_result content

Less common but real. Early on I had a tool that returned full database rows for every record it touched — north of 400KB per call. The API rejected it. Treat 200KB as the practical ceiling for a single tool_result content. For any tool that might brush against it, run a two-tier summarization.

async function safeToolResult(rawOutput: string, summarize: (s: string) => Promise<string>): Promise<string> {
  const MAX = 180 * 1024;
  if (rawOutput.length <= MAX) return rawOutput;
 
  const head = rawOutput.slice(0, 30_000);
  const tail = rawOutput.slice(-30_000);
  const middle = rawOutput.slice(30_000, -30_000);
  const summarized = await summarize(middle);
 
  return [
    "=== HEAD (first 30KB raw) ===",
    head,
    `=== MIDDLE (summarized from ${middle.length} bytes) ===`,
    summarized,
    "=== TAIL (last 30KB raw) ===",
    tail,
  ].join("\n");
}

I use Claude Haiku 4.5 for the summarization step. For a long time I carried a vague sense that Haiku was "an order of magnitude cheaper" than Sonnet, and when I finally pulled up Anthropic's pricing page the gap turned out to be narrower than I'd assumed.

Exactly one third on both input and output — not one order of magnitude. Summarizing a 120KB middle section costs about 30,000 input tokens and returns roughly 1,500 output tokens, so a single pass runs (30,000 × $1 + 1,500 × $5) ÷ 1,000,000 = $0.0375. Twenty passes a day still lands around $22 a month.

That's a cost I'm happy to pay, but it isn't quite "free" either. Since I stopped collapsing input and output into one blended rate and started carrying the two numbers separately, my estimates have matched the invoice.

The oversize-content variant of tool_result could not be submitted went from 3–4 incidents per month to zero over six months.

Triage checklist before you retry

Whenever the error appears, walk this list top to bottom before reaching for retries. In my experience the first two items resolve 70% of the cases:

• Block count mismatch: prior assistant message's tool_use count differs from your tool_result count → cause 1
• A text block is sitting inside the tool_result-only user message → cause 2; split the text into the next turn
• Logs show streaming interruption, timeout, or SIGTERM just before the failure → cause 3; recover from checkpoint
• A specific tool_use_id carries content above 180KB → cause 4; summarize and resubmit
• None of the above → retry. Anthropic-side transient state shows up once or twice a month at most

Since I rolled this checklist out in March 2026, no tool_result could not be submitted incident has held a scheduled job down for more than 30 minutes.

Turning the checklist into one function

Walking a checklist by eye at 7am means skipping a step sooner or later. These days I hand the failed response body and the message array I was about to send to a single function that returns one of the four causes, and the classification goes straight into the alert.

type Cause = "id-mismatch" | "ordering" | "interrupted" | "oversize" | "transient";
 
interface ClassifyInput {
  errorBody: string;                 // body of the failed API response
  pendingIds: string[];              // every tool_use.id from the prior assistant turn
  submitted: Array<{ tool_use_id: string; content: string }>;
  hadStreamInterruption: boolean;    // raised from the preceding run log
}
 
const OVERSIZE_LIMIT = 180 * 1024;
 
function classifyToolResultFailure(inp: ClassifyInput): Cause {
  // 1) Oversize first: one offending block makes every other check meaningless
  if (inp.submitted.some((s) => s.content.length > OVERSIZE_LIMIT)) return "oversize";
 
  // 2) Compare the id sets in both directions — missing and extra
  const sent = new Set(inp.submitted.map((s) => s.tool_use_id));
  const missing = inp.pendingIds.filter((id) => !sent.has(id));
  const extra = [...sent].filter((id) => !inp.pendingIds.includes(id));
  if (missing.length > 0 || extra.length > 0) {
    // With interruption evidence, this is a crash to recover from, not a coding bug
    return inp.hadStreamInterruption ? "interrupted" : "id-mismatch";
  }
 
  // 3) For ordering drift, the API's wording is more reliable than local state
  if (/must (be|immediately) follow|unexpected `?text`?/i.test(inp.errorBody)) return "ordering";
 
  // 4) Nothing matched
  return "transient";
}

The order of the checks is deliberate. Oversize goes first because a single offending block will let every later check pass cleanly. And when the ids disagree, the interruption flag wins, because the same missing-id symptom points at two opposite fixes — your tool execution code, or your resume path. I ran without that branch at first, filed every interruption-born failure under "implementation bug", and spent about two weeks shipping fixes that couldn't have worked.

Retry only when the classifier says transient. Everything else goes to a human immediately. Drawing that one line made my morning log review noticeably shorter.

Three quirks that aren't in the docs

Six months of running into this in production surfaced three behaviors worth knowing:

First, an empty string for tool_result content is unstable. Prefer a short literal like "no result" or "completed" over an empty string. I saw the downstream agent's completion rate improve by 8% just by tightening that one field.

Second, parallel tool_use fan-out above 5 sharply increases the failure rate. My own numbers: under 1 per month at fan-out 4, around 2 per month at 5, more than 5 per month at 6+. I cap concurrency at 4 with a semaphore. That correlation may well be an artifact of my tools running long individually — but picking a ceiling costs nothing either way.

Third, do not fire the next request the instant you see stop_reason: "tool_use" on the streaming message_delta. There seems to be a small server-side settle delay; firing immediately occasionally triggers could not be submitted. A 50ms sleep before the next request is what finally took the residual incidents to zero in my setup.

Line those three up and a pattern shows through: in long-running agents, the center of gravity in error handling drifts quietly from retrying toward restoring state. tool_result could not be submitted is the first place that drift burns you if you haven't made it yet.

Everything so far assumed you assemble the messages array yourself. From here on, the same four causes get mapped onto what you can actually see and do from Claude Code or the desktop app.

When the banner shows up in Claude Code or the desktop app

You get this error even when you never touch the messages array yourself. What's happening underneath is identical — an API-layer integrity error on that array. The only difference is who assembled it: the client, not you.

Which means the four causes above still apply. Here's how they present from the client side:

Ignore the banner's wording and suspect the tool_use_id and content fields first. Through a client, that's still the shortest path.

Reading the real error in DevTools

The banner hides the underlying API response, but you can usually pull the truth out of your browser. Open DevTools → Network tab, filter by messages or complete, reproduce the failure, and inspect the failed POST. The response body almost always contains a precise reason — messages.X.content.Y.tool_use_id: required or tool_result content size exceeds limit. That single line tells you which of the three causes above you're dealing with, and the rest of this article becomes a targeted lookup instead of a hunt.

The 60-second recovery checklist

Try these in order. Half the time, you're back to work before you finish the list.

1. Stop reusing the broken thread. Start a fresh chat and re-send the same prompt. A corrupted message history will keep failing at the same step forever.
2. Hard-reload the app. ⌘ + Shift + R on macOS, Ctrl + Shift + R on Windows. Stale state in the renderer is a real cause.
3. Reset Claude Code session. Run claude --reset-session, or move the failing session file under .claude/sessions/ to a backup folder.
4. Disable suspect MCP servers. claude mcp list to see what's connected, then claude mcp remove <name> to detach the most recently added server. Reproduce; if it stops failing, you've found the culprit.

If the error vanishes after step 1 alone, the root cause was a poisoned message history. Once an invalid tool_result enters a conversation, every subsequent turn replays it and fails at the same place.

Fixing it from your API / SDK code

When you call the API directly and the error keeps coming back, the fix lives in how you build the tool_result. This is the helper I drop into every project that uses tool use:

# Validate every tool_result before sending it back to Claude.
# Catches None, bytes, oversized payloads, and missing tool_use_id.
import json
from typing import Any
 
def build_tool_result(tool_use_id: str, raw: Any) -> dict:
    if raw is None:
        # Sending None makes Claude see an empty content field and stall.
        content = "(no result)"
    elif isinstance(raw, (dict, list)):
        # Always JSON-serialize structured data. default=str rescues
        # datetimes, UUIDs, sets — anything json doesn't know natively.
        content = json.dumps(raw, ensure_ascii=False, default=str)
    else:
        content = str(raw)
 
    # Anything much beyond 200KB tends to get rejected at the API edge.
    if len(content) > 200_000:
        content = content[:200_000] + "\n... (truncated)"
 
    if not tool_use_id:
        raise ValueError(
            "tool_use_id is empty — there is no matching tool_use in the previous assistant turn"
        )
 
    return {
        "type": "tool_result",
        "tool_use_id": tool_use_id,
        "content": content,
    }

The expected outcome is straightforward: when you pass this dict to messages.create, the call goes through silently and Claude returns the next assistant turn. The tool_use_id must always equal one of the tool_use.id values from the immediately preceding assistant message — mismatch this and you'll surface a derivative error like messages: each tool_result.tool_use_id must match a prior tool_use.id.

One pattern worth knowing: when the underlying tool actually failed, set is_error: true and put the error string in content. Claude is genuinely good at recovering from a clearly labeled error. Pretending the call succeeded is a far worse experience for the user.

For a deeper map of the request/response cycle, Running Claude API Parallel Tool Use in Production and The Line That Disappears at 100K cover the two axes that matter most here: fan-out and return size.

Extra checks for MCP and Skills users

When the banner shows up only with MCP servers or Skills active, the bug usually lives in the subprocess, not in Claude. In my own incident, my MCP was passing a Buffer straight through and the JSON serializer silently dropped fields. Things to verify:

• Log the full MCP response with console.error(JSON.stringify(result)) before returning it. The output should be human-readable JSON.
• Confirm the response size is reasonable. Returning raw image bytes is enough to blow past the limit instantly.
• Check whether your Skill's Python or Node script crashed mid-run, leaving stdout truncated.
• If your network is shaky, raise the timeout_ms for long-running tools — a timed-out MCP call frequently surfaces as this exact error.

If MCP behavior looks generally off, isolate the connection and capability layers first with The MCP Server Connects Fine and Still Hands Back Zero Tools. It saves a lot of guesswork.

When nothing else works

If you've exhausted the steps above and the error still reproduces, this is the full reset I run. In the past six months, it has resolved every stubborn case I've hit:

1. Archive or delete the broken chat, but copy any custom Project system prompt into a plain text file first.
2. Disable browser extensions temporarily. CORS-bending and request-rewriting extensions can mangle requests in surprisingly creative ways.
3. Detach MCP servers one at a time and find the smallest configuration that still reproduces the error.
4. Once you've isolated the offender, patch that specific server — stringify outputs, drop large binaries, add a try/except around the handler.
5. Toggle off any Skill or Custom Instruction you added recently. New extensions are statistically the most likely cause.

If the issue persists after all of that, an upstream Anthropic incident is a rare but real possibility. Cross-check with Complete Troubleshooting Guide: When Claude Won't Respond, Is Slow, or Stops Mid-Response — it lists the public status pages worth keeping bookmarked.

Logging strategies that make the next failure easy

The reason this error feels so opaque is that the banner alone tells you nothing — by the time it's on screen, the offending payload is already gone. A small amount of preventive logging removes that blindness for good. I add three things to every project that uses tool use:

• Log the full request body for every messages.create call to a local file when running in development. A 200-line transcript of one bad call is worth more than a week of guessing.
• Hash and length-check the content of every tool_result before sending. If the hash matches a previous failure, route around it.
• Capture the tool_use_id pairing in your structured logs so you can grep for pair=tool_42 status=rejected later.

# Lightweight tracer for tool_use / tool_result pairing.
# Drop into your project; turn on with TOOL_DEBUG=1.
import os, json, logging, hashlib
 
log = logging.getLogger("claude.tools")
log.setLevel(logging.DEBUG if os.getenv("TOOL_DEBUG") == "1" else logging.INFO)
 
def trace_tool_result(tool_use_id: str, content: str) -> None:
    digest = hashlib.sha1(content.encode("utf-8")).hexdigest()[:10]
    log.debug(
        "tool_result id=%s len=%d sha=%s preview=%r",
        tool_use_id, len(content), digest, content[:120],
    )

The expected output is one log line per tool turn, including the first 120 characters of the payload. When the next "could not be submitted" arrives, the offending line is immediately above the failure timestamp. I've shaved hours off post-mortems with nothing more elaborate than this.

Manufacturing all four failures on your own machine

When I first wrote the classifier, the only way to check it was to wait for a real failure — a handful a month, at best. A function you can exercise four times a month isn't a function you trust. So I stopped waiting for the breakage and started manufacturing it.

Three of the four shapes — mismatch, ordering, oversize — need nothing but a hand-built message array. No API call, no spend.

// classify.test.ts — runs under `node --test` or vitest
import { test } from "node:test";
import assert from "node:assert/strict";
import { classifyToolResultFailure } from "./classify";
 
const base = { errorBody: "", pendingIds: ["t1", "t2"], hadStreamInterruption: false };
 
test("mismatch: one result never came back", () => {
  const got = classifyToolResultFailure({
    ...base,
    submitted: [{ tool_use_id: "t1", content: "ok" }],
  });
  assert.equal(got, "id-mismatch");
});
 
test("interrupted: same gap, but the fix lives somewhere else", () => {
  const got = classifyToolResultFailure({
    ...base,
    submitted: [{ tool_use_id: "t1", content: "ok" }],
    hadStreamInterruption: true,
  });
  assert.equal(got, "interrupted");
});
 
test("oversize: one offender settles it before any other check runs", () => {
  const got = classifyToolResultFailure({
    ...base,
    submitted: [
      { tool_use_id: "t1", content: "x".repeat(200_000) },
      { tool_use_id: "t2", content: "ok" },
    ],
  });
  assert.equal(got, "oversize");
});
 
test("ordering: local state looks fine, only the API text knows why", () => {
  const got = classifyToolResultFailure({
    ...base,
    errorBody: "`tool_result` blocks must immediately follow the `tool_use`",
    submitted: [
      { tool_use_id: "t1", content: "ok" },
      { tool_use_id: "t2", content: "ok" },
    ],
  });
  assert.equal(got, "ordering");
});

The second and third cases are the exact pair I kept confusing early on. The symptom is identical — an id with no matching result — but the repair belongs to the tool-execution path in one case and to the resume path in the other. Pinned as fixtures, that branch fails in a test run rather than in production.

The interrupted case is the one you can't fake, because something genuinely has to be severed. I have claude-haiku-4-5-20251001 hand back four cheap parallel tools, then send SIGTERM to my own process right after the second tool_result goes out. It costs a fraction of a cent per run, and I haven't found an honest way to exercise the resume path without it.

Breakage is something to manufacture, not something to wait for. Since I flipped that order, classifier mistakes show up in a test run instead of in the next morning's log.

Next time the banner appears, do one thing before you reach for retry: count the tool_use blocks in the previous assistant turn and count the tool_result blocks you sent back. Make that single habit automatic and half the triage is already done.

When the counts disagree, the validator helper and the tracer above are what turn the mismatch into a fix. Keep them in the repo alongside one hard rule for every tool you write — never return raw bytes, never return None, always honor the tool_use_id you were handed. Nearly every occurrence I've seen in the wild breaks exactly one of those three.