Skip to Content

My AI agent fails only for some users. How do I find the cause?

Rius shows which end users hit failures on the Users page, then takes you from a user’s failed trace to the span and exception behind it. Sort the list by failed traces, open the affected user, and compare their numbers with the agent’s. Then open the failing trace to see the error span, and look for what the affected users share. For the wider routine, see Monitor AI agents in production.

How it works

Rius reads the end user from user.id on each span (it also accepts enduser.id and enduser.pseudo.id). A trace with no end user on any span counts as anonymous.

  • Users list. The Users page lists traces, failed traces and cost per user for a window of 15m to 30d. It shows the top 50 for the chosen sort. To reach anyone else, search by exact user ID.
  • A user’s page. It shows Failed traces, Error rate, Cost and TTFT p50 (median time to first token) for that user. If their error rate or cost per trace is well above the agent’s own numbers on Agents, the cause is probably specific to that user: their data, their account settings or the kind of questions they ask.
  • Trace status. A failed trace is a run whose root span ended in error. A recovered trace had errored child spans, but the agent retried or fell back and the run finished clean. Error rate counts both, so a user with a high error rate and few failed traces is being rescued by retries or fallbacks.
  • Inside a trace. The waterfall highlights failed spans along the path from the root to the error. For an error span, the detail panel leads with the exception and traceback.

Set it up

  1. Check that your traces carry an end user. Open Users and read the line above the list, for example “400 of 471 traces carry an end user”. A large anonymous row means some code paths run outside a user scope. Set the user with rius.user in Python or withUser in TypeScript. Prefer an opaque user ID to an email.
  2. Tag your releases, so you can tell whether the failures started with a change:
RIUS_MAIN_AGENT_VERSION=prompt-v12      # the agent definition: prompt, tools, policy
RIUS_SERVICE_VERSION=2026.09.29-a41f3c  # the build or deploy
  1. On Users, sort by Failed. If a handful of users account for most failures, note what they have in common, such as account settings, data size or language, before you change anything that affects everyone.
  2. Open the top user. Compare Failed traces, Error rate, Cost and TTFT p50 with the agent’s numbers on Agents. Check Agents that served this user to see which agent to inspect.
  3. Open a trace from Failed traces on their page, or click View all in Traces for the full list filtered to that user. Read Exploring traces for the views. Start on the highlighted span path and read the exception and traceback. Check the trace’s retry chains, such as fetch_article · 3 attempts · recovered, to see whether a tool fails repeatedly for this user. For a trace with several model calls, the context growth strip plots input tokens per call, so a runaway prompt or long history shows up there.
  4. Compare with a run that worked. On the open trace, use Compare runs against another run of the same agent. It shows which steps changed, were added or were dropped, and where cost or latency moved. On a model call, Since previous llm call on the Input / Output tab shows what each step added to the prompt, if your setup captures content.
  5. Look for the shared trait. On Traces, click Add filter and pick any span or resource attribute your agents send, such as a plan, region or model, and see whether the failures cluster on one value. Filters combine with AND and live in the URL, so you can share the link with a teammate.
  6. On the agent’s page, open Exceptions to see whether the errors come from one failure type or several. Open Versions and Drift to see whether the failed rate rose with a release.

What you get

  • A ranked list of the users with the most failures, so you start with the clearest case.
  • A per-user comparison against the agent’s own numbers, which tells you whether the problem is the user or the agent.
  • The failing span, its exception and traceback, and the retry chain around it.
  • A side-by-side view of a failing run and a working one.
  • An attribute filter that shows whether the affected users share a value, with a link you can hand to a teammate.
  • A way to tell a real failure from a recovered one, so you do not chase runs the agent already handled.
  • From a support ticket, a path to the failing span in a few clicks: type the customer’s exact user ID, click Find, and open the trace from the time they wrote in.

When something else fits

  • If failures hit every user, start on Agents instead: Exceptions shows the failure types, and Versions and Drift show whether a release caused them.
  • If your traces carry no end user, the user views stay empty. Filter on another attribute in Exploring traces until you set user.id.

Still stuck? Get help

Last updated on
Quickstart