How do I find sessions that hit errors in OpenHands?

Rius marks an OpenHands conversation as failed when any of its spans errors, so you open the Traces page, set the status filter to failed and narrow to your agent. Each conversation is one trace, and its conversation id is the Rius session. Open a failed trace to see the exact step, with the exception and traceback on the error span.

How it works

Rius records every OpenHands conversation as one trace: the conversation, each agent.step, and the model and tool calls inside it. The conversation id becomes the session, so a multi-turn conversation groups together.

A trace’s status comes from its spans, not from anything your agent reports:

• completed: the run finished and no span failed.
• failed: at least one span has an OpenTelemetry ERROR status, normally a recorded exception.
• running… (filter value incomplete): the run has started and has no end yet.

A failed trace whose root span finished cleanly is badged recovered. Child spans errored, the agent retried or fell back, and the run itself completed. The errors are still counted.

Two things make OpenHands sessions easy to pick out. The agent name comes from agent.name metadata, or from the script name if you set none. The user comes from user_id if you pass one. Conversations without a user land in the anonymous row on the Users page.

A failed terminal command is not an error span. A non-zero exit code sits in the tool output, not the span status, so that trace still reads completed. A rotated or expired model key does produce an error span, because the first model call fails.

Set it up

1. Send your OpenHands traces to Rius with the three OTEL_EXPORTER_OTLP_TRACES_* variables. The OpenHands guide has the exact values and the web app and Enterprise variants. This is part of the wider Coding agents setup.
2. Name the agent and the user when you create the conversation, so you can filter on both later:

conversation = Conversation(
    agent=agent,
    workspace=".",
    user_id="dev@example.com",
    observability_metadata={"agent.name": "fib-writer"},
)

3. Open Traces in the console and pick a time range. The default is 7 days. Set the status filter to failed, then click your agent in any row to filter to it. Click a user cell to see one developer’s failures. Web-app conversations show under the agent openhands-agent-server.
4. Add more filters if the list is long. Add filter takes any span or resource attribute, and filters combine with AND.
5. Open a failed trace. The waterfall highlights the path from the root to the error, and the detail panel for an error span leads with the exception and traceback. Press ]e to jump to the next failed span and [e for the previous one.
6. To see only the failing steps, use the Spans tab. Filter by status, or pick Tool in the All kinds menu to look at failed tool calls. The Session link in a trace header opens Spans filtered to that conversation. You can also paste a session ID into the search box.

What you get

• A list of the OpenHands conversations that hit an error, filtered by agent, user, time range and status.
• The failing step in each one, with the exception and traceback, plus the model calls and tool calls around it.
• recovered badges that separate runs that retried and finished from runs that failed outright.
• Per-developer failures on the Users page, when you pass user_id.
• Alerts on repeated failures. The pre-defined Consistent Error Pattern alert fires when the same error appears at least 3 times across at least 2 runs within 5 minutes. A bad model key is the typical case. Attach a channel to get it in Slack, email or a webhook.
• Questions from an MCP client. The Rius MCP server has an agent_error_groups tool, so you can ask for the top error groups for an agent this week.

Failed commands and stuck loops need a different route, because the trace still reads completed. A run stopped by OpenHands’ stuck detector also reads completed. The pre-defined Tool Loop alert covers it. It fires when the same tool is called with the same arguments at least three times in a row in one trace.

When something else fits

• If your sessions fail through a command that exits non-zero, filter by agent and look at the terminal tool spans, or rely on the Tool Loop alert, since those runs show as completed.
• For Claude Code sessions, the same trace list and failed filter apply. See Track Claude Code usage and cost across a team, and read Exploring traces for the full filter and status reference.
• OpenHands Cloud cannot send traces to Rius, so its sessions will not appear.

Related