How do I track failed tool calls in Claude Code?

Rius records each failed tool call in a Claude Code session as an error on a tool span in that session’s trace, once you turn tracing on for a folder with the Rius plugin. Run /rius:enable-here for the span, tool name and error type, or /rius:enable-content-here to add the error details. You find the failures in the trace waterfall, on the Users page, or by asking Claude through the Rius MCP server.

How it works

One Claude Code session is one trace. Each tool call (Bash, Read, Edit, MCP tools and so on) gets its own span under the model call that made it, and a failed call is marked as an error on that span. Subagents get their own spans too, so a failure inside a subagent shows nested under the call that started it.

What a failed call records depends on how you enabled the folder:

• Structure only (/rius:enable-here): the span, its timing, the tool name and the error type. For a shell call, also the kind of command it ran (test, build, lint, package, git or other) and its exit code.
• With content (/rius:enable-content-here): everything above, plus the tool’s inputs, such as the command or file path, its output, and the error details of the failed call. The plugin replaces the secrets it recognizes before export. This is best effort, so a secret in a format it does not know is sent.

Tool durations are exact. Model-call durations are approximate, because Claude Code’s transcript records when a reply finished but not when the request went out.

Set it up

1. Install the plugin in a terminal. Setup, sign-in and every option are covered in full in the Claude Code plugin guide.

   claude plugin marketplace add glassflow/rius-coding-agents && claude plugin install rius@rius-coding-agents

2. Sign in from Claude Code. In the browser, pick a workspace and click Connect.

   /rius:login

3. Turn tracing on for the folder where you work. Tracing is off everywhere until you do this. Choose one command:

   /rius:enable-here
   /rius:enable-content-here

   Use the first if you only need to know which tool failed and with what error type. Use the second if you also want the error text, the command that ran and its output. A session that is already open is traced from its start once you enable its folder.

4. Check the state. The first line should read Rius tracing: on, and Content: shows whether the folder sends structure only or content.

   /rius:status

5. Work as usual, then find failures in Rius:

   • Open the trace list in the console and open the session. The waterfall shows every turn, model call and tool call in order, and a failed tool call is marked as an error.
   • Open the Users page. A developer’s Error rate counts sessions with at least one errored span, and their page’s Failed traces list shows those sessions, recovered ones included. The Failed traces tile counts only runs whose root span failed, which a Claude Code session never does.
   • Run /mcp, pick rius, sign in once, and ask Claude, for example: “Show me my last failed session and which tool call went wrong.”

Rolling this out to a team? Track Claude Code usage and cost across a team covers one shared workspace and per-developer views. The wider set of agents is on Coding agents.

What you get

• The exact failed step in a session: the tool span marked as an error, placed in the turn and model call that led to it.
• The tool name and error type for every failure, even from folders that send structure only.
• For shell calls, the command kind and exit code in both modes.
• With content on, the error details, tool input and output for the failed call.
• A per-developer error rate on the Users page, a list of each developer’s sessions with an errored tool call, and live sessions in the trace list while they run.
• Plain-language questions from the terminal about your last failed session, through the Rius MCP server the plugin brings.

Two things the tracing does not give you. In a structure-only folder, the error text of a failed call is not sent. And the Users and Agents figures count a session only once it has ended, so a session that Claude Code crashed or killed never counts there, though the trace list still shows its spans.

When something else fits

• If you need the error text but your team does not want prompts and file contents in the workspace, agree on which repos use /rius:enable-content-here, since everyone in the workspace can read what is sent.
• If you are building your own agent on the Claude Agent SDK rather than using Claude Code, use the SDK integration instead of this plugin.

Related