ErrLookup › Background articles › ToolError: Tool Execution Failed — What This Error Class Means and How to Fix It

ToolError: Tool Execution Failed — What This Error Class Means and How to Fix It

ToolError is an error class raised by agent frameworks and tool runtimes (such as oh-my-pi and OpenManus) when a tool call — a browser action, file read/write, session operation, or model-backed helper — cannot complete. This page explains the common mechanisms behind ToolError, the typical triggers (missing parameters, unsupported capabilities, changed or invalid session state, unreachable infrastructure), and the fixes and prevention habits that hold across the family.

Distilled from 422 documented records across 5 repositories.

Background

ToolError is not a single message from a single library. It is a catch-all error class that agent frameworks use on the boundary between an LLM-driven tool call and the thing the tool touches: a browser daemon, a sandbox container, a session file, a debug adapter, or a model registry. Because the class name is generic, the actual diagnostic lives in the message text, and each library fills that text with its own remediation hints — for example 'Set PUPPETEER_EXECUTABLE_PATH to use an existing Chrome/Chromium binary', 'Current adapter does not support disassembly', or 'command is required for custom_request'. Reading the embedded message is the first debugging step in every case.

Most ToolErrors come from three broad mechanisms. The first is parameter and capability validation: tools refuse calls before doing work when a required field is missing ('command is required for custom_request'), a selector matches nothing ('no window matches ...'), a file type is unsupported, or a debug adapter did not advertise the needed DAP capability. The second is state drift: the runtime holds cached records or registrations and finds the world changed underneath them — a vibe worker whose parent session file was switched or compacted before a turn, a merge conflict whose marker block was edited after registration, a checkpoint already consumed by a prior rewind, or a question session whose answering client disconnected. The third is infrastructure and resolution failure: a Chromium download fails, a browser relay endpoint is unreachable, a sandbox file read/write throws, or a model resolver cannot find any model matching a configured role or tier.

From the caller's side the error usually arrives as a rejected tool result delivered back into the agent loop rather than a stack trace in your own code. Many runtimes deliberately wrap low-level exceptions this way: OpenManus's sandbox file operators catch every exception from the sandbox client and re-raise as ToolError with the original message appended (discarding the traceback via 'from None'), and oh-my-pi converts image size/decode failures into ToolError so an actionable message reaches the model instead of a corrupt payload entering the transcript. Some messages are themselves generated summaries — a bulk conflict resolution where every file failed throws its multi-line per-file report as the error text, and a failed auto-backgrounded eval cell surfaces its final output as the error message. So the string you see is often the most (and sometimes the only) diagnostic available.

The family varies across libraries in strictness and shape. oh-my-pi (the largest contributor of records) uses ToolError pervasively with feature-detection and fail-closed security paths — e.g. refusing skill:// paths that resolve outside a plugin root, or gating language backends behind configuration flags like eval.jl and PI_JL. FoundationAgents/OpenManus uses it as a broad wrapper around sandbox operations with the original exception message embedded, and also as a dispatch fallback for unrecognized tool commands (one exact lowercase command set, which catches LLM-issued typos like 'delete_plan' or ' remove'). xai-org/grok-build raises it for session-level failures such as a user-question channel closing when the client disconnects. Because conventions differ — some messages embed remediation, some embed only the underlying exception string — fixes are always message-specific even though the prevention patterns repeat.

Common causes

What usually fixes it

Go deeper

Documented occurrences

…and 402 more across the corpus — use search.

Honest provenance: generated on 2026-08-31 from AI-assisted analysis of the linked records. See how records are made.