Skip to content

Latest commit

 

History

History
126 lines (81 loc) · 5.98 KB

troubleshooting.mdx

File metadata and controls

126 lines (81 loc) · 5.98 KB
title Troubleshooting
description Common errors of run_code, search_tools and add_hint, their causes and fixes, and the known limits.

Troubleshooting

Errors

A nested call fails with "no verdict" in auto mode

The server-side auto mode classifier gave no verdict for mcp__…

Cause: an older version of Claude Code. In auto mode, it denies a nested call that no allow rule matches.

Fix: update Claude Code to 2.1.301 or newer. If you cannot update, add an allow rule for the tool. The first result with this error names the tool in the section "No allow rule". See Auto mode and allow rules.

"the sandbox exited without a result"

Cause: Node did not start or stopped before the program returned. The stderr part of the result gives the reason.

  • If stderr contains bad option: --permission, the Node version is older than 22.13. Install a newer Node, or set the option node to a newer executable.
  • If stderr contains not found, Claude Code cannot find node. Set the option node to an absolute path.

See Configuration.

"the program did not run, because some calls have wrong names"

Cause: the check before a run found a tool name or an argument name that is wrong. No call occurred.

Fix: the model corrects the names that the result gives. If a name is correct, the model passes the arguments as a variable. Then the check does not read them.

If the result says a deny rule hides it and the tool name is correct, a deny rule takes the tool out of the session. Remove the rule, or do the task without the tool. See Deny rules.

"… refused: Claude requested permissions to use …, but you haven't granted it yet"

Cause: in claude -p, no rule allows the nested call, and nobody can approve it.

Fix: add an allow rule for the tool, or pass it in --allowedTools. See Headless sessions need allow rules.

"readFile: no permission to read …"

Cause: Claude Code needs your approval to read the file. readFile reads no file that needs a prompt.

Fix: put the file in the project, or add a Read allow rule for it. See Files.

"timeout after … ms"

Cause: the program ran longer than timeoutSeconds. Often an MCP call did not reply. The run footer then shows that call with did not finish.

Fix: make the program do less work in one run, or increase timeoutSeconds. If a call did not finish, find out why its server does not reply. When the program ends, the plugin waits at most 1 second more for its calls. It does not start the calls that wait in the queue. A program runs at most 8 calls at one time.

"more characters cut, return less data"

Cause: the shown text is longer than 20,000 characters.

Fix: the model must return only the fields that it needs. If you see this often, ask the model to filter in the program. If the note gives a recall(n) number, the next program can return a part of the whole value with no new MCP call.

"only MCP tools … can be called"

Cause: the program called a built-in tool, such as Bash, or a code-mode tool. A program can call only MCP tools.

"hint files and saved functions steer the model, so they cannot be written with file tools"

Cause: the model tried to write a hint file or a function file with Write, Edit or NotebookEdit. The guard denies this.

Fix: let the model propose the hint with add_hint or the function with save_function, then approve it in the band. Or edit the file in your own editor, then approve the changed file in the band.

"lib.… is not a saved function"

Cause: the program called a saved function that does not exist, or that did not load.

Fix: let the model run search_tools to see the saved functions. If you wrote or changed the file yourself, approve it in the band first. If it still does not load, start Claude Code with claude --debug. The debug log names each function file that does not load, and why.

"no MCP server in this session offers resources"

Cause: the program called resources or readResource, but no connected server has resources.

Fix: connect a server that has resources, or use its tools.

"… failed; see the debug log"

Cause: a code-mode tool or the hint-file guard stopped with an error.

Fix: start Claude Code with claude --debug and do the step again. The lines that start with code-mode: give the error. The debug log also names each hint file that the plugin cannot read, and each hint file that applies to no server.

"project hints are off"

Cause: the model proposed a project hint, and the option projectHints is off.

Fix: let the model propose a user hint, or turn on projectHints for a project that you trust.

Limits

  • search_tools reads argument types from a types file that Claude Code writes. Claude Code writes it in an interactive session with hot reload or with --plugin-dir. It does not write it for headless claude -p runs. It does not write it for a plugin from a marketplace.
  • Without the types file, search_tools shows the argument names of earlier calls, and tells the model to use ToolSearch for the schema. ToolSearch puts the full tool definition into the context, so the program saves fewer tokens. Claude Code gives a plugin no other way to read the schema of an MCP tool.
  • A nested call cannot pass an argument with the name tool. The plugin API uses this name for the tool name.
  • On Linux, the sandbox has a network block only where unshare -rn works. Ubuntu 24.04 and later do not allow it by default. See Sandbox.
  • The add_hint row with buttons is not tested in the terminal yet.
  • Cowork and the cloud sessions of the web and mobile apps cannot show the band. Approve their proposals in another session. See In Cowork and in cloud sessions.