Tool failures

A "tool failure" is when the agent calls a tool, the tool returns an error, and the agent surfaces that error in the conversation. This page covers the most common ones and how to fix them.

File-system tools

read_file: ENOENT — file not found

The path doesn't exist or has a typo. Check with ls first. Note: the agent uses paths relative to the working directory unless you give it an absolute path.

edit_file: file modified since last read

The agent reads then edits, expecting the file to be unchanged in between. If you (or another process) modified the file in that window, the edit is rejected to prevent overwriting your changes. The agent will re-read and retry — this is normal once or twice; if it's persistent, something else is rewriting the file.

write_file: EACCES — permission denied

The user running InsightWorker doesn't have write permission. Check ls -la <path> and adjust ownership/perms.

Shell

bash: command not found

The command isn't on the InsightWorker process's PATH. Two failure modes:

1. Different PATH per surface — VS Code's PATH might differ from your terminal's, especially on macOS. Add full paths or set PATH in ~/.insightworker/.env.
2. Tool not installed — install via brew/apt/etc.

Long-running commands hang

Default bash timeout: 2 minutes. For longer tasks set per-call:

bash(command="...", timeout=600000)   # 10 minutes

Max is 10 minutes. For apps that genuinely need >10min, use & and a polling pattern, or split into multiple steps.

SharePoint tools

sharepoint_list: 401 Unauthorized

Microsoft Graph token expired or app registration missing permissions. See authentication/microsoft-graph.md. For Sites.Selected apps, verify per-site grants via the PowerShell snippet in that doc.

sharepoint_read: 404 Not Found for a path that exists

InsightWorker normalizes Graph's /drive/root: prefix internally. If you're seeing 404 on a known path, two checks:

1. The path uses backslashes (Windows-style) — Graph wants forward slashes
2. The site URL passed to sharepoint_list doesn't match the actual site (e.g. /sites/Underwriting vs /sites/UnderwritingTeam)

Output truncated

SharePoint tools return one record per line for compact output. If your record exceeds the per-line limit, it's marked [truncated]. Narrow the query or fetch the file directly with sharepoint_read.

JIRA tools

jira_search: 401 Unauthorized

Token expired or wrong basic-auth format. JIRA Cloud uses email + API token (not username + password). See authentication/jira-api-token.md.

jira_search: returns 0 results

JQL syntax error or wrong project key. Verify in the JIRA UI by running the same JQL in Issues → Advanced search.

Perplexity

perplexity_search: 401

Bad pplx- key. Regenerate at the Perplexity console.

Costs higher than expected

Each call hits sonar-pro or sonar (you control via env). For chat-style use, sonar is ~10x cheaper. Set:

PERPLEXITY_MODEL=sonar

Mermaid

mermaid_render: mmdc not found

The local mermaid CLI isn't installed. InsightWorker falls back to mermaid.ink (a public renderer). For air-gapped environments, install locally:

npm install -g @mermaid-js/mermaid-cli

mermaid.ink: invalid diagram

Your diagram has a syntax error mermaid can't parse. The error message includes the line. Common: missing semicolons, unmatched brackets, unsupported diagram type.

Provider-level errors

These look like tool failures but originate from the LLM provider:

400 max_tokens not supported, use max_completion_tokens

You're on an old InsightWorker version calling a GPT-5 family model. Upgrade to the latest CLI.

404 only supported in v1/responses

GPT-5-pro / o1-pro / *codex models need the Responses API. Upgrade to the latest CLI.

429 rate-limited

Provider tier hit. Wait, switch model, or upgrade provider plan.

When the loop detector fires

If a tool fails 3 times in a row, the agent stops. Read the first error, not the loop-detector message — that first one is the real cause. See permissions-and-safety/loop-detector.md.

See also

• bedrock-credentials.md — Bedrock-specific errors
• max-iterations.md — when the agent runs out of iterations
• permissions-and-safety/loop-detector.md — the safety net

Source: docs/troubleshooting/tool-failures.md in the public repo. Open a PR with corrections.