close
OpenClaw Internals
  • English

      • Session Transcript Corruption

      Overview

      This guide covers session transcript corruption issues in OpenClaw, based on src/agents/session-transcript-repair.ts. The Anthropic API requires strict pairing between tool calls and tool results. When transcripts become corrupted, the automatic repair system intervenes.

      Symptoms

      API Errors

      • Error message: "unexpected tool_use_id found in tool_result blocks"
      • HTTP 400 responses from Anthropic API
      • Agent API call rejected immediately

      Agent Stops Responding

      • Agent processes messages but never responds
      • No visible error to user
      • Internal logs show tool result pairing issues

      Duplicate Tool Results

      • Same tool_use_id appears multiple times
      • Multiple results for single tool call
      • Transcript contains redundant entries

      Orphaned Tool Results

      • Tool result messages without corresponding tool calls
      • tool_result blocks not immediately following assistant turns
      • Free-floating toolResult entries in session

      Root Causes

      1. Orphaned Tool Results (Lines 203-352)

      Tool results not immediately paired with their assistant tool calls:

      Detection logic:

      // Expected: assistant message with toolCall, then user message with matching toolResult
// Corrupt: toolResult appears later or in wrong position

      Common causes:

      • Message insertion/deletion during session
      • Concurrent modifications to transcript
      • Failed message append operations

      Repair: Move toolResult directly after matching assistant turn

      2. Duplicate Tool Results

      Same tool_use_id appears in multiple tool results:

      Detection: Track seen tool_use_ids, flag duplicates Common causes:

      • Retry logic that appends results multiple times
      • Race conditions in message handling
      • Manual transcript editing errors

      Repair: Drop duplicate toolResults, keep first occurrence

      3. Free-Floating Tool Results

      Tool results without any corresponding assistant tool call:

      Detection: Orphaned toolResults with no matching tool_use_id in transcript Common causes:

      • Tool call message deleted but result remained
      • Incomplete session history loading
      • Corruption during JSONL serialization

      Repair: Insert synthetic error toolResult with message "[openclaw] missing tool result in session history..."

      4. Incomplete Tool Calls (Lines 250-263)

      Assistant messages with stopReason "error" or "aborted" containing partial tool calls:

      Detection logic:

      if (msg.role === "assistant" &&
    (msg.stopReason === "error" || msg.stopReason === "aborted")) {
  // Skip tool call extraction - these are incomplete
  continue;
}

      Common causes:

      • LLM API error during tool call generation
      • User or system abort during streaming
      • Network timeout mid-response

      Repair: Skip tool call extraction, no toolResult expected

      Recovery Mechanisms

      Automatic Repair System

      The repairToolUseResultPairing() function implements comprehensive repair: