Skip to Content

My Claude Agent SDK agent fails only for some users. Why?

Rius shows which users’ runs fail and on which span, so you can see what those users have in common. Sort the Users page by failed traces, open a failing user’s trace, and read the error on the root span or the turn’s generation. The cause is usually something specific to those users, such as their data, account settings or the questions they ask.

How it works

The Claude Agent SDK runs the Claude Code runtime in a separate process, so Rius traces it with two explicit pieces. An observe wrapper makes each task the root AGENT span, and one manual generation wraps the query() loop and records model, tokens and cost for the whole turn. The full setup is on the Claude Agent SDK integration page.

That shape tells you what a failure looks like:

  • A failed trace has at least one span with an OpenTelemetry ERROR status, normally a recorded exception. Rius derives this from the spans, not from anything your agent reports.
  • The error sits on one of two spans. The root span is your task. The generation under it is the runtime turn.
  • The runtime’s inner work is invisible. Tool calls, sub-turns and file operations happen inside the Claude Code process and produce no spans. If a failure starts in there, you see it only as an error or an odd result on the turn.
  • A recovered run is a failed trace whose root span finished without an error of its own. It is badged recovered, and its errors are still counted.

To see per-user patterns, each task has to run inside a user scope. rius.user sets user.id on every span of the request. A trace with no user on any span counts as anonymous. Wrap each task in rius.session() too, so one conversation is one session.

Set it up

  1. Confirm the integration is in place. This is the base SDK plus the Claude Agent SDK, and the claude CLI must be installed and authenticated.
pip install glassflow-rius claude-agent-sdk

This is the integration page task plus a user scope and a raise on ResultMessage.is_error, where the runtime reports a failed turn.

import asyncio import rius from claude_agent_sdk import ( AssistantMessage, ClaudeAgentOptions, ResultMessage, TextBlock, query, ) from rius import SpanKind rius.init(api_key="ri_...", service_name="my-agent") MODEL = "claude-haiku-4-5" @rius.observe(name="handle-task", kind=SpanKind.AGENT) async def handle_task(task: str) -> str: options = ClaudeAgentOptions(model=MODEL, max_turns=1) parts = [] with rius.start_as_current_generation( "claude_agent_turn", model=MODEL, provider="anthropic", input=task ) as gen: async for message in query(prompt=task, options=options): if isinstance(message, AssistantMessage): parts.extend( b.text for b in message.content if isinstance(b, TextBlock) ) elif isinstance(message, ResultMessage): usage = message.usage or {} gen.set_usage( input_tokens=usage.get("input_tokens"), output_tokens=usage.get("output_tokens"), cache_read_input_tokens=usage.get("cache_read_input_tokens"), cache_write_input_tokens=usage.get("cache_creation_input_tokens"), ) if message.is_error: # Raising records the error on the generation and the root span raise RuntimeError(f"Claude Agent SDK run failed: {message.subtype}") answer = "".join(parts) gen.set_output(answer) return answer async def main() -> None: # Enter the user scope before the root span starts, so every span carries user.id with rius.user("user_8412"), rius.session("ticket-1093"): print(await handle_task("Summarize the open tickets for my account.")) asyncio.run(main())
  1. Run each task inside rius.user with your own user id, and prefer an opaque id to an email. Open Users and look at the line above the list, such as “400 of 471 traces carry an end user”. A large anonymous row means some code paths run outside a user scope, and failures there cannot be tied to a person.
  2. On Users, set the window and sort by Failed. If a handful of users account for most failures, look at what they share before you change anything that affects everyone: account settings, data size, language.
  3. Open one failing user’s page. Compare Failed traces, Error rate and Cost per trace with the agent’s own numbers on the Agents page. A user well above the agent’s average points to something specific to that user. The Failed traces list shows their six latest errored runs, recovered ones included.
  4. Open a failing trace in Exploring traces. In the waterfall, failed spans are highlighted from the root to the error, and the detail panel leads with the exception and traceback. Check the Input / Output tab for the task text that user sent.
  5. Check the generation’s model section for tokens and, when the model’s context window is known, how much of it was used. A user with long history can fill the window where others do not.
  6. Repeat the comparison on the trace list. Click a user cell to filter the list to that user, or add filters on any attribute your agent sends, such as the model, and compare failed runs with completed ones.
  7. Use the Spans tab with the status filter to list every failed span at once. The search box matches session IDs, so pasting one lists every span in that conversation.

What you get

  • A ranked list of users by failed traces, so you can tell whether failures are spread out or concentrated.
  • A per-user page with failed traces, error rate, cost, sessions and the agents that served them, from the support ticket to the failing span in a few clicks.
  • The exception and traceback on the span that failed, plus the prompt and reply when content capture is on.
  • A clear boundary. Because the runtime’s internal steps produce no spans, the turn’s totals and its error are what you read, not the individual tool calls.
  • A way to catch it next time. Keep the Users page sorted by Failed as your routine check. Rius also has pre-defined alerts, such as Consistent Error Pattern, and custom rules on error rate that you can filter by service or agent, with webhook, email and Slack channels. Those alerts watch the agent as a whole, so the Users page is where you find which users are behind a rise.

For the broader routine, see Monitor AI agents in production.

When something else fits

  • If the failing step is inside the Claude Code runtime, such as a tool call or file operation, the spans cannot show it, so reproduce it with the same user’s input in the runtime directly.
  • If the same tasks fail for everyone, look at the agent as a whole rather than at users. The integrations overview covers how the other frameworks record their inner steps.

Still stuck? Get help

Last updated on