[BUG] API Error: 400. Each `tool_use` block must have a corresponding `tool_result` block in the next

Getting similar:

API Error: 400 {"type":"error","error":{"type":"invalid_request_error","message":"messages.227: tool_use ids were
found without tool_result blocks immediately after: toolu_01NMZHiv9T448pvCZFDiaLUH. Each tool_use block must
have a corresponding tool_result block in the next message."},"request_id":"req_011CTPY1zNW6yij4WkeqJEDJ"}

I've been having this error for several days now, practically in every session:
API Error: 400 {"type":"error","error":{"type":"invalid_request_error","message":"messages.137: tool_use ids were found without tool_result blocks immediately after: toolu_01SU9yXafXLVeMDEgtRkae2w. Each tool_use block must have a corresponding tool_result block in the next message."},"request_id":"req_011CTPYz16iUecMKw8j2Nwt6"}

I'm having the same issue

I had the same issue but got Claude to troubleshoot and fix itself. here's the summary on how it self healed:

⏺ 🎯 Root Cause & Fix Summary

The Problem:

Claude's conversation state had broken message flow structure, not just orphaned tool_use blocks as initially thought.

Root Cause Discovery:

1. Initial Diagnosis: Seemed like orphaned tool_use blocks without tool_result entries
2. Deeper Investigation: Found all 18 tool_use IDs DID have corresponding tool_result entries
3. Real Issue: 18 consecutive assistant messages (lines 925-942) violated Claude's conversation protocol

Conversation Flow Problem:

• Expected Pattern: assistant (tool_use) → user (tool_result) → assistant (tool_use) → user (tool_result)
• Broken Pattern: assistant → assistant → assistant × 18 → user → user × 18

The Fix:

Surgical Structure Repair - Removed the malformed section (lines 925-942) while preserving 92.4% of conversation history (924/999 lines).

Key Insight:

The error message tool_use ids were found without tool_result blocks immediately after was literal - Claude requires tool_result blocks in the
immediately following message, not just somewhere later in the conversation.

Why This Worked:

• Restored proper alternating message structure
• Conversation now ends cleanly with a complete assistant text message
• No orphaned tool_use blocks remain in active conversation flow
• All remaining tool_use/tool_result pairs follow proper protocol

Result: Claude can now continue normally with full conversation context preserved! ✅

My observation is that this occurs when the conversation is interrupted. Sometimes the interruption doesn't "take" and Claude 'forks' - one fork will continue running despite the interruption, and the other fork will be interrupted.

Then, the messages from the two threads get interspersed and everything grinds to a halt.

I have used /bug to report this at least once.

<details>

<summary>
I have tried reordering the lines using this script that Claude wrote me, but it didn't seem to fix the problem adequately.
</summary>

#!/usr/bin/env python3
"""
Fix Claude conversation history files with out-of-order tool calls and results.

This script repairs JSONL conversation files where tool_use and tool_result blocks
are mismatched or out of order, which causes Claude API errors.

The key insight is that tool_result blocks must immediately follow their corresponding
tool_use blocks in the conversation. When they're out of order, the API rejects them.

Approach:
1. Backup the original file
2. Parse all messages and extract tool_use/tool_result pairs with their positions
3. Reorder messages so tool_result immediately follows its tool_use
4. Remove orphaned tool_use blocks that have no matching results
5. Remove orphaned tool_result blocks that have no matching tool_use

Usage:
    python fix_claude_conversation.py conversation.jsonl              # Dry run
    python fix_claude_conversation.py --fix conversation.jsonl        # Apply fixes
    python fix_claude_conversation.py --fix ~/.claude/projects/*/*.jsonl  # Batch
"""

import argparse
import json
import shutil
import sys
from pathlib import Path


def parse_jsonl(file_path: Path) -> list[dict]:
    """Parse JSONL file and return list of message objects."""
    messages = []
    try:
        with open(file_path, encoding="utf-8") as f:
            for line_num, line in enumerate(f, 1):
                line = line.strip()
                if not line:
                    continue
                try:
                    data = json.loads(line)
                    messages.append(data)
                except json.JSONDecodeError as e:
                    print(f"Warning: Skipping malformed JSON on line {line_num}: {e}")
    except Exception as e:
        print(f"Error reading {file_path}: {e}")
        return []

    return messages


def extract_tool_info_with_positions(
    messages: list[dict],
) -> tuple[dict[str, tuple[int, dict]], dict[str, tuple[int, dict]]]:
    """
    Extract tool_use and tool_result blocks from messages with their positions.

    Returns:
        tool_uses: {tool_id: (message_index, message_data)}
        tool_results: {tool_id: (message_index, message_data)}
    """
    tool_uses = {}
    tool_results = {}

    for i, msg in enumerate(messages):
        if not isinstance(msg, dict) or "message" not in msg:
            continue

        message = msg["message"]
        if not isinstance(message, dict) or "content" not in message:
            continue

        content = message["content"]
        if not isinstance(content, list):
            continue

        for item in content:
            if not isinstance(item, dict):
                continue

            if item.get("type") == "tool_use" and "id" in item:
                tool_id = item["id"]
                tool_uses[tool_id] = (i, msg)

            elif item.get("type") == "tool_result" and "tool_use_id" in item:
                tool_id = item["tool_use_id"]
                tool_results[tool_id] = (i, msg)

    return tool_uses, tool_results


def has_tool_use(msg: dict) -> str | None:
    """Check if message has tool_use and return the tool ID."""
    if not isinstance(msg, dict) or "message" not in msg:
        return None

    message = msg["message"]
    if not isinstance(message, dict) or "content" not in message:
        return None

    content = message["content"]
    if not isinstance(content, list):
        return None

    for item in content:
        if isinstance(item, dict) and item.get("type") == "tool_use" and "id" in item:
            return item["id"]

    return None


def has_tool_result(msg: dict) -> str | None:
    """Check if message has tool_result and return the tool_use_id."""
    if not isinstance(msg, dict) or "message" not in msg:
        return None

    message = msg["message"]
    if not isinstance(message, dict) or "content" not in message:
        return None

    content = message["content"]
    if not isinstance(content, list):
        return None

    for item in content:
        if (
            isinstance(item, dict)
            and item.get("type") == "tool_result"
            and "tool_use_id" in item
        ):
            return item["tool_use_id"]

    return None


def fix_conversation(messages: list[dict]) -> tuple[list[dict], int, int, int]:
    """
    Fix conversation by reordering tool_use/tool_result pairs and removing orphans.

    Returns:
        fixed_messages: List of repaired messages
        removed_tool_uses: Number of orphaned tool_use messages removed
        removed_tool_results: Number of orphaned tool_result messages removed
        reordered_pairs: Number of tool pairs that were reordered
    """
    tool_uses, tool_results = extract_tool_info_with_positions(messages)

    # Find orphaned items
    orphaned_tool_uses = set(tool_uses.keys()) - set(tool_results.keys())
    orphaned_tool_results = set(tool_results.keys()) - set(tool_uses.keys())

    # Track which messages we've processed
    processed_indices = set()
    fixed_messages = []
    removed_tool_uses = 0
    removed_tool_results = 0
    reordered_pairs = 0

    for i, msg in enumerate(messages):
        if i in processed_indices:
            continue

        tool_use_id = has_tool_use(msg)
        tool_result_id = has_tool_result(msg)

        if tool_use_id:
            if tool_use_id in orphaned_tool_uses:
                # Remove orphaned tool_use
                removed_tool_uses += 1
                print(f"  Removing orphaned tool_use: {tool_use_id}")
                processed_indices.add(i)
            elif tool_use_id in tool_results:
                # This tool_use has a matching result
                result_idx, result_msg = tool_results[tool_use_id]

                # Add the tool_use message
                fixed_messages.append(msg)
                processed_indices.add(i)

                # Check if result is in the correct position (next message)
                if result_idx != i + 1:
                    reordered_pairs += 1
                    print(
                        f"  Reordering tool pair: {tool_use_id} (result moved from position {result_idx} to follow {i})"
                    )

                # Add the tool_result message immediately after
                fixed_messages.append(result_msg)
                processed_indices.add(result_idx)
            else:
                # This shouldn't happen based on our analysis, but handle gracefully
                print(
                    f"  Warning: tool_use {tool_use_id} found but not in results dict"
                )
                fixed_messages.append(msg)
                processed_indices.add(i)

        elif tool_result_id:
            if tool_result_id in orphaned_tool_results:
                # Remove orphaned tool_result
                removed_tool_results += 1
                print(f"  Removing orphaned tool_result: {tool_result_id}")
                processed_indices.add(i)
            # If it's not orphaned, it will be handled when we process its tool_use

        else:
            # Regular message (not tool_use or tool_result)
            fixed_messages.append(msg)
            processed_indices.add(i)

    return fixed_messages, removed_tool_uses, removed_tool_results, reordered_pairs


def write_jsonl(messages: list[dict], file_path: Path) -> None:
    """Write messages to JSONL file."""
    with open(file_path, "w", encoding="utf-8") as f:
        for msg in messages:
            json.dump(msg, f, separators=(",", ":"))
            f.write("\n")


def backup_file(file_path: Path) -> Path:
    """Create backup of file and return backup path."""
    backup_path = file_path.with_suffix(file_path.suffix + ".backup")
    shutil.copy2(file_path, backup_path)
    return backup_path


def analyze_file(file_path: Path, apply_fix: bool = False) -> bool:
    """
    Analyze and optionally fix a conversation file.

    Returns True if file needed fixing, False otherwise.
    """
    print(f"\nAnalyzing: {file_path}")

    if not file_path.exists():
        print("  Error: File not found")
        return False

    messages = parse_jsonl(file_path)
    if not messages:
        print("  Error: No valid messages found")
        return False

    print(f"  Total messages: {len(messages)}")

    # Extract tool information
    tool_uses, tool_results = extract_tool_info_with_positions(messages)

    print(f"  Tool uses: {len(tool_uses)}")
    print(f"  Tool results: {len(tool_results)}")

    orphaned_tool_uses = set(tool_uses.keys()) - set(tool_results.keys())
    orphaned_tool_results = set(tool_results.keys()) - set(tool_uses.keys())

    print(f"  Orphaned tool uses: {len(orphaned_tool_uses)}")
    print(f"  Orphaned tool results: {len(orphaned_tool_results)}")

    # Check for ordering issues
    ordering_issues = 0
    for tool_id, (use_idx, _) in tool_uses.items():
        if tool_id in tool_results:
            result_idx, _ = tool_results[tool_id]
            if result_idx != use_idx + 1:
                ordering_issues += 1

    print(f"  Out-of-order tool pairs: {ordering_issues}")

    if orphaned_tool_uses:
        print(
            f"  Orphaned tool_use IDs: {list(orphaned_tool_uses)[:3]}{'...' if len(orphaned_tool_uses) > 3 else ''}"
        )

    if orphaned_tool_results:
        print(
            f"  Orphaned tool_result IDs: {list(orphaned_tool_results)[:3]}{'...' if len(orphaned_tool_results) > 3 else ''}"
        )

    needs_fixing = (
        len(orphaned_tool_uses) > 0
        or len(orphaned_tool_results) > 0
        or ordering_issues > 0
    )

    if not needs_fixing:
        print("  ✅ No issues found")
        return False

    if not apply_fix:
        print("  ⚠️  Issues found - run with --fix to repair")
        return True

    # Apply fixes
    print("  🔧 Applying fixes...")

    # Create backup
    backup_path = backup_file(file_path)
    print(f"  📁 Backup created: {backup_path}")

    # Fix conversation
    fixed_messages, removed_uses, removed_results, reordered = fix_conversation(
        messages
    )

    # Write fixed file
    write_jsonl(fixed_messages, file_path)

    print("  ✅ Fixed:")
    print(f"    - Removed {removed_uses} orphaned tool_use messages")
    print(f"    - Removed {removed_results} orphaned tool_result messages")
    print(f"    - Reordered {reordered} tool pairs")
    print(f"  📊 Final message count: {len(fixed_messages)}")

    return True


def main() -> None:
    parser = argparse.ArgumentParser(
        description="Fix Claude conversation history files with tool call/result ordering issues",
        formatter_class=argparse.RawDescriptionHelpFormatter,
        epilog="""
Examples:
  python fix_claude_conversation.py conversation.jsonl                    # Dry run
  python fix_claude_conversation.py --fix conversation.jsonl              # Apply fixes
  python fix_claude_conversation.py --fix ~/.claude/projects/*/*.jsonl    # Batch fix
        """,
    )

    parser.add_argument("files", nargs="+", help="Conversation files to analyze/fix")
    parser.add_argument(
        "--fix", action="store_true", help="Apply fixes (default is dry-run mode)"
    )

    args = parser.parse_args()

    # Expand file patterns
    file_paths = []
    for pattern in args.files:
        path = Path(pattern).expanduser()
        if path.is_file():
            file_paths.append(path)
        else:
            # Try globbing
            matches = list(Path(pattern).expanduser().parent.glob(Path(pattern).name))
            if matches:
                file_paths.extend([p for p in matches if p.is_file()])
            else:
                print(f"Warning: No files found matching {pattern}")

    if not file_paths:
        print("Error: No valid files specified")
        sys.exit(1)

    print(f"Mode: {'FIXING' if args.fix else 'DRY RUN (analysis only)'}")
    print(f"Files to process: {len(file_paths)}")

    files_needing_fix = 0

    for file_path in file_paths:
        try:
            if analyze_file(file_path, args.fix):
                files_needing_fix += 1
        except Exception as e:
            print(f"  ❌ Error processing {file_path}: {e}")

    print("\n📊 Summary:")
    print(f"  Files processed: {len(file_paths)}")
    print(f"  Files needing repair: {files_needing_fix}")

    if files_needing_fix > 0 and not args.fix:
        print("  💡 Run with --fix to apply repairs")


if __name__ == "__main__":
    main()

</details>

I found that deleting the specific tool use calls worked to a point, but sometimes it would cause the conversation history to get corrupted to the point where it would be blanked out.

I found that rewinding to before the first problematic tool call worked.

Moving the tool use result message back up to sit with the tool use message did not seem to be sufficient. I wonder whether it's because I didn't re-map the parentUuids as well – the tool use result had a parentUuid reflecting its actual order in the jsonl file rather than where it "should" have been up above...

I am also losing hours of work due to this.

This kind of worked: https://gist.github.com/awesomo4000/e4dcee5675a725a2ec8f44ce6d02b4a0

I can reproduce this fairly consistently by replying to Claude between the last message and when my PreStop hook finishes. It appears that the PreStop hook starts a thread and my message before its response starts another, and the threads become interleaved.

Horribly annoying this issue. Hours of contexts lost. The only thing that I have found that works is to clear the history.

I can also reproduce this by sending a message at any point between Stop hook execution and when execution actually stops.

I can stop it from happening by pressing Esc before sending a message. Once it starts, I have to ctrl-C out of Claude Code and then Esc-Esc back to before I sent the message that triggered the bug.

Nothing is working for me. This error crops up every few calls. It obviously only happens when tool-use (search, etc.) is being done. Is there no fix to this? Pretty big and annoying bug.

Remains in 2.0, though it is less frequent.

Symptoms are similar - happens after Stop hook and I see two parallel threads running.

I do notice that whereas in 1.x I could trigger it only by sending a message after the Stop hook triggers, it seems to happen with no user input whatsoever in 2.0.

Rewinding the conversation to the last Stop hook reliably recovers for me.

Since 2.0, sending any instruction back to Claude Code in a hook now always triggers a Missing Tool Result Block error and bricks the conversation.

It can be reproduced consistently in the Stop hook.

(./claude/settings.json)

{
  "hooks": {
    "Stop": [
      {
        "matcher": "",
        "hooks": [
          {
            "type": "command",
            "command": "python3 $CLAUDE_PROJECT_DIR/.claude/script.py"
          }
        ]
      }
    ]
  }
}

(./claude/script.py)

#!/usr/bin/env python3
import json
import sys

output = {
    "continue": True,
    "stopReason": "Summarization needed.",
    "suppressOutput": True,
    "decision": "block",
    "reason": "You must now summarize your work."
}
print(json.dumps(output))
sys.exit(2)

Same issue - filed it as separate bug:

Bug Description
Claude Code is very brittle in conjunction with tool calls. In case a tool request does not return, or a new message is submitted before the tool returns, it is out of sync.
Claude is then not responsive again. also / commands are not available anymore. So it's not even possible to /compact or write out the chat summary. Only option is to exit and start fresh. But this means, that all the prior context is gone. -c does not work as continuation includes the entire history and this also means that the errors persist.

This is not a rare issue. It happens (in longer conversations) EVERY time. Really, really annoying. I use claude with hooks (stop hook, pre-tool use, post-tool use, etc.)
around 20 agents, around 12 custom commands and several mcp servers. Use claude context for context indexation, sequential thinking and other relevant mcp tools.

I would want to either be able to a) make Claude reset the tool chain (unblock by removing the tool_use ids that did not return), or allow to compact. What is mandatory: It cannot be, that such an issue breaks follow-up prompts or commands. Literally NOTHING than exiting works anymore after this. So no possibility to clear, compact, write out, etc.

API Error: 400 {"type":"error","error":{"type":"invalid_request_error","message":"messages.107: tool_use ids were found without tool_result blocks immediately after:
toolu_01Qou6gYEL7GyAd9VFp5LqoU. Each tool_use block must have a corresponding tool_result block in the next message."},"request_id":"req_011CTjmWkHa93MQMtijMNVtp"}

Environment Info

Platform: darwin
Terminal: iTerm.app
Version: 2.0.5
Feedback ID: 5ff09ed8-15f3-44d0-b727-c25aef312fcb
Errors

[{"error":"Error: 400 {\"type\":\"error\",\"error\":{\"type\":\"invalid_request_error\",\"message\":\"messages.80: tool_use ids were found without tool_result blocks immediately after: toolu_01JkHyGazjoUvLzBW426G5pk. Each tool_use block must have a corresponding tool_result block in the next message.\"},\"request_id\":\"req_011CTjkswJpHzgrj2dXpeK9A\"}\n at B4.generate (file:///Users/simonscheurer/.npm-global/lib/node_modules/@anthropic-ai/claude-code/cli.js:895:18688)\n at yP.makeStatusError (file:///Users/simonscheurer/.npm-global/lib/node_modules/@anthropic-ai/claude-code/cli.js:1034:2131)\n at yP.makeRequest (file:///Users/simonscheurer/.npm-global/lib/node_modules/@anthropic-ai/claude-code/cli.js:1034:5344)\n at process.processTicksAndRejections (node:internal/process/task_queues:105:5)\n at async E2B.dG1.model (file:///Users/simonscheurer/.npm-global/lib/node_modules/@anthropic-ai/claude-code/cli.js:1120:39804)\n at async dG1 (file:///Users/simonscheurer/.npm-global/lib/node_modules/@anthropic-ai/claude-code/cli.js:1120:27733)\n at async E2B (file:///Users/simonscheurer/.npm-global/lib/node_modules/@anthropic-ai/claude-code/cli.js:1120:39958)\n at async file:///Users/simonscheurer/.npm-global/lib/node_modules/@anthropic-ai/claude-code/cli.js:1120:34180\n at async ZH0 (file:///Users/simonscheurer/.npm-global/lib/node_modules/@anthropic-ai/claude-code/cli.js:1120:9568)\n at async r11 (file:///Users/simonscheurer/.npm-global/lib/node_modules/@anthropic-ai/claude-code/cli.js:1120:34150)","timestamp":"2025-10-03T06:02:15.416Z"},{"error":"Error: 400 {\"type\":\"error\",\"error\":{\"type\":\"invalid_request_error\",\"message\":\"messages.80: tool_use ids were found without tool_result blocks immediately after: toolu_01JkHyGazjoUvLzBW426G5pk. Each tool_use block must have a corresponding tool_result block in the next message.\"},\"request_id\":\"req_011CTjkt2GUEcLR4m8sfsgWX\"}\n at B4.generate (file:///Users/simonscheurer/.npm-global/lib/node_modules/@anthropic-ai/claude-code/cli.js:895:18688)\n at yP.makeStatusError (file:///Users/simonscheurer/.npm-global/lib/node_modules/@anthropic-ai/claude-code/cli.js:1034:2131)\n at yP.makeRequest (file:///Users/simonscheurer/.npm-global/lib/node_modules/@anthropic-ai/claude-code/cli.js:1034:5344)\n at process.processTicksAndRejections (node:internal/process/task_queues:105:5)\n at async E2B.dG1.model (file:///Users/simonscheurer/.npm-global/lib/node_modules/@anthropic-ai/claude-code/cli.js:1120:39804)\n at async dG1 (file:///Users/simonscheurer/.npm-global/lib/node_modules/@anthropic-ai/claude-code/cli.js:1120:27733)\n at async E2B (file:///Users/simonscheurer/.npm-global/lib/node_modules/@anthropic-ai/claude-code/cli.js:1120:39958)\n at async file:///Users/simonscheurer/.npm-global/lib/node_modules/@anthropic-ai/claude-code/cli.js:1120:34180\n at async ZH0 (file:///Users/simonscheurer/.npm-global/lib/node_modules/@anthropic-ai/claude-code/cli.js:1120:9568)\n at async r11 (file:///Users/simonscheurer/.npm-global/lib/node_modules/@anthropic-ai/claude-code/cli.js:1120:34150)","timestamp":"2025-10-03T06:02:16.898Z"},{"error":"Error: 400 {\"type\":\"error\",\"error\":{\"type\":\"invalid_request_error\",\"message\":\"messages.107: `tool_use
Note: Error logs were truncated.

fyi - Also referenced in many other issues including the ones listed here
https://github.com/anthropics/claude-code/issues/8894#issuecomment-3368364011

Been working with Stop hooks (that conditionally block claude from stopping with a message that essentially says "are you sure you're done? check the following to be sure..." that until today has been working REALLY well - no errors, catches things I want it to do that it forgets, etc. Today ran into this issue for the first time.

For me, after reading this thread, I decided to do a /compact to see if that did what I needed, and it seemed to work. Of course /compact has its own tradeoffs, but in case this helps others get unblocked, I thought I'd mention it here.

This issue has been inactive for 30 days. If the issue is still occurring, please comment to let us know. Otherwise, this issue will be automatically closed in 30 days for housekeeping purposes.

This issue has been automatically closed due to 60 days of inactivity. If you're still experiencing this issue, please open a new issue with updated information.

This issue has been automatically locked since it was closed and has not had any activity for 7 days. If you're experiencing a similar issue, please file a new issue and reference this one if it's relevant.