Tool & MCP Failure Errors

Solutions for MCP tool failures, function call errors, schema mismatches, plugin crashes, and tool timeout issues in AI agents.

38 solutions in this category

• API Tool Returns HTML Error Page Instead of JSON — JSONDecodeError on Error Response
  Agent calls an API expecting JSON. API returns an HTML error page (500, maintenance page, or WAF block). json.loads()...
• Agent Calls Destructive Tools Without Confirmation
  The agent deletes files, sends emails, drops database records, or publishes content without asking the user first. On...
• Agent Calls Tool with Wrong Argument Types — Silent Failure or Type Error
  Agent passes a string where the tool expects an integer, or a list where a string is expected. Tool raises TypeError ...
• Agent Calls Wrong Tool When Tool Names or Descriptions Are Similar
  The agent has get_user and get_user_profile — it calls the wrong one. It has search_documents and search_web and pick...
• Agent Enters an Infinite Tool Call Loop — Never Returns a Final Answer
  The agent calls a tool, gets a result, calls the same tool again with slightly different arguments, gets another resu...
• Agent Hangs Forever When Tool Call Times Out — No Timeout Handling
  Agent calls an external tool or API with no timeout. The remote server is slow or unresponsive. Agent blocks indefini...
• Agent Ignores Tool Response Errors — Continues as If Tool Succeeded
  Tool returns {"error": "permission denied"} or {"success": false}. Agent reads the response, says 'the file was writt...
• Agent Ignores Tool Result and Uses Prior Knowledge Instead
  Agent calls a tool, receives an accurate result, then answers using its training knowledge instead—leading to outdate...
• Agent Misinterprets Tool Error Codes as Success
  Agent treats HTTP 4xx/5xx responses, partial results, or error payloads as successful tool outputs and continues with...
• Agent Only Processes First Page of Results — Silently Misses Remaining Pages
  Agent calls an API that returns paginated results. It reads the first page (100 items) and considers the task done. T...
• Agent Passes Wrong Argument Types to Tools
  The agent calls tools with strings where integers are expected, None where lists are required, or nested objects inst...
• Agent calls APIs with incorrect schemas or parameters
  Agent invokes tools/APIs with wrong parameter types, missing required fields, or incorrect schemas. API calls return ...
• Bug: Intermittent 'thinking is enabled but reasoning_content is missing in assistant tool call message' error crashes session
  During normal Claude Code sessions (using official Claude models), an intermittent API 400 error occurs that immediat...
• Bypass permission mode still prompts for permissions
  When selecting "bypass" permission mode at session start, Claude Code still prompts for permission on tool calls. Thi...
• Context corruption exposes raw API errors to chat surface
  When a session transcript becomes corrupted (orphaned without matching ), the raw Anthropic API error is delivered di...
• Discord /reset creates sessions with thinkingLevel=off for OpenAI Codex models, breaking tool calling (regression in 2026.3.23)
  Regression (worked before, now
• Feature Request: Split gateway daemon and agent runtime for container isolation
  Currently, the OpenClaw gateway daemon is a single Node.js process that handles everything: messaging (Telegram/Disco...
• Feature Request: messages.suppressToolErrorWarnings for regular sessions (not just heartbeat)
  Currently, suppresses non-mutating tool errors but not mutating tool errors (like , , , etc.). The check in always re...
• File Not Found — Agent Confuses Relative and Absolute Paths
  Agent uses relative path 'data/input.csv' which resolves to different locations depending on working directory. Works...
• MCP Server Fails to Start — spawn ENOENT Error on Startup
  MCP server process fails to launch with 'spawn ENOENT' error. Agent starts without the tool available. Usually caused...
• Mobile (iOS): no streaming output visibility for long-running Bash commands
  When running long-running tool calls (container builds, package installs, cargo builds, etc.) through Claude Code on ...
• Ollama tool call arguments serialized as string instead of object — breaks tool loop
  When an Ollama model returns a tool call, OpenClaw stores as a JSON string (OpenAI format). When this assistant messa...
• Session corruption loop: API timeout during tool_use causes permanent broken state
  When an embedded agent run times out mid-execution while a block is in-flight, the session JSONL file is saved in a c...
• Session lock timeout causes channel handler failures during long operations
  Channel handlers (especially Telegram) frequently fail with lock timeout when the agent is processing any long operat...
• Session parser crashes on OpenAI-compatible tool IDs (functions.xxx:0)
  OpenClaw's session parser crashes when reloading sessions containing tool_use IDs generated by models accessed throug...
• Subprocess Hangs Because stdout Buffer Is Full — Deadlock in Tool Execution
  Agent runs a subprocess with subprocess.run() or Popen(). Process produces large output, stdout pipe fills up, subpro...
• Third-Party API Schema Changed — Agent Breaks Silently
  External API adds a required field, renames a key, or changes a value's type. Agent continues sending old request for...
• Tool Call Returns Empty Result — Agent Proceeds as if Successful
  Tool call returns 200 OK with empty body, null result, or empty array. Agent interprets this as success and continues...
• Tool Call Times Out and Agent Gives Up — No Retry Logic
  Agent calls a tool that takes too long, hits a timeout, and immediately gives up or reports failure. The tool would h...
• Tool Schema Validation Error — Malformed JSON Schema Rejects Tool Definition
  Tool definition fails validation with 'invalid schema' or 'tool_use_param_invalid'. The input_schema is not valid JSO...
• WebSearch tool error: thinking is enabled but reasoning_content is missing
  The tool consistently returns a 400 error with the following
• Webhook Not Received — Silent Delivery Failure
  Agent registers a webhook endpoint but events never arrive. No error from the sender. Endpoint looks correct. Webhook...
• [Feature] Graceful context compaction — PreCompact hook data + background compaction option
  Context compaction is currently a hard wall — a synchronous operation that pauses the session, lossy-compresses the c...
• [Feature]: Option to suppress tool call error notifications in Telegram
  Add a channel-level option (e.g. channels.telegram.showToolErrors: false) to suppress automatic tool call error notif...
• fix: Anthropic SDK crashes when proxy/relay retransmits SSE stream — patch & workaround
  When using OpenClaw with a third-party API proxy/relay (e.g., nexus-style relay), the bot intermittently fails to res...
• fork_session drops parallel tool call branches from JSONL history
  When using with via the Claude Agent SDK, the CLI's fork logic drops parallel tool call branches from the previous se...
• loopDetection: toolCallHistory persists across heartbeat cycles, causing false positives
  in session state carries over between heartbeat cycles. When a heartbeat runs, its tool calls get pushed onto the his...
• message tool fails silently when multiple channels configured — no context-aware fallback
  When multiple messaging channels are configured (e.g. + ), the tool always fails on first call if the LLM agent omits...

Related Guide

The Tool Failure Error Guide covers root causes, prevention patterns, and checklists for this category of errors.