---
title: "Find issues in your agent's traces"
description: "Find recurring problems in your agent's traces that no judge is checking for yet."
sidebar:
  label: "Issues overview"
seo:
  title: "Find issues in your agent's traces | Judgment Docs"
  description: "Find recurring problems in your agent's traces that no judge is checking for yet."
---

Judges catch the problems you already knew to look for; Issues is for the ones you didn't. It's an agent that reads your recent traces, groups failures by root cause, and reports the ones that keep happening.

Issues needs only traces. If you have judges, detection uses their labels as extra signal.

## What an Issue looks like

In the [lunch-order agent](/documentation/start/example-agent), `get_menu` keeps timing out for one restaurant and the agent drops it without telling the user. Detection reports that as a **High** severity Issue with trend **First seen**, titled "Menu lookups time out and the agent silently drops the restaurant".

{/* SCREENSHOT: issue detail page for the menu-timeout issue, showing Severity, Description/Impact/Consider, Evidence and Incidents, dark mode */}

Every Issue has:

- A **Severity**: Critical, High, Medium or Low. You can change it.
- A trend: **First seen**, **Ongoing**, or **Regressed** when an Inactive Issue comes back.
- **Description** (what fails), **Impact** (who it affects and how often) and **Consider** (directions for a fix).
- **Evidence**: the traces that show the failure, with what happened, where in the trace, and when.
- **Incidents**: a chart of occurrences over time. The top of the Issue shows when it was first and last seen.
- **Activity**: status changes and comments from your team.

## How detection decides what to report

Detection is an agent run that happens on a schedule or when you ask for it. Each run reads your recent traces and looks for errors, tool failures, latency and cost outliers, negative judge labels, and failures that only show up in what the agent said or did. It groups what it finds by root cause, so two failures with the same error message but different causes become two Issues.

It reports a root cause once it keeps recurring, or right away when a single trace shows severe impact, such as unsafe behavior, data loss, or harm to a user. Every Issue cites the traces that show the failure, so you can check it yourself. Your detection instructions tell it what to prioritize.

If detection already reported a root cause, a later run updates that Issue with new evidence instead of opening a duplicate. It leaves Dismissed, Monitored and Merged Issues alone.

## How detection starts

- Project setup starts it. A new project gets its first detection run during setup. See the [Quickstart](/documentation/start/quickstart).
- You can turn it on from Issues. If detection isn't on yet, **Turn on** asks what to look for, then **Start Detection** runs it. See [Set up detection](/documentation/issues/set-up-detection).
- After that it runs on a schedule or when you ask. Set a schedule in **Detection settings**, or choose **Run now**.

Detection runs as a built-in agent, so it also appears under **Scheduled** as a built-in task. Like other agent runs, it uses Judgment Units (JU). See [Billing and plans](/documentation/administration/billing-and-plans).

## What happens to an Issue

```mermaid
flowchart LR
  New["Needs review"] -->|"linked to a judge and label"| Mon["Monitored"]
  New -->|"Dismiss issue"| Dis["Dismissed"]
  New -->|"no new occurrences for N days (if turned on)"| Ina["Inactive"]
  Ina -->|"happens again (Regressed)"| New
  Dis -->|"Reopen"| New
  Ina -->|"Reopen"| New
```

New Issues land in **Needs review**. From there, an Issue can move to one of these statuses:

| Status | How an Issue gets there | What happens next |
| --- | --- | --- |
| **Monitored** | A judge and label are linked to it. | The Issue keeps this status. |
| **Dismissed** | You select **Dismiss issue**. | Judgment ignores future occurrences. |
| **Inactive** | You turned on **Mark stale issues inactive**, and the Issue had a stretch with no new occurrences. The setting starts at 10 days. | If it happens again, Judgment sends it back to **Needs review** as **Regressed**. |
| **Merged** | It was set through the [MCP tools](/documentation/reference/mcp-tools). | It leaves the inbox, detection stops updating it, and its status can't change again. |

**Monitor with Judge** opens a Judgment Agent conversation to configure a judge that labels traces with this pattern. Opening the conversation alone does not complete the handoff. [Triage and fix](/documentation/issues/triage-and-fix) covers each action.

## Issues or judges?

Most patterns start as an Issue and become a judge once you know exactly what to watch for. A judge labels every trace, so you can count, filter and alert on the problem. **Monitor with Judge** starts that handoff.

**[Set up detection](/documentation/issues/set-up-detection)**

Instructions, schedule, Slack reports and inactivity.

**[Triage and fix](/documentation/issues/triage-and-fix)**

Work the inbox and hand Issues to your coding agent.

**[Cookbook: Root-cause an Issue](/documentation/issues/cookbook-root-cause-an-issue)**

The menu-timeout Issue, from evidence to fix to a judge.