> ## Documentation Index
> Fetch the complete documentation index at: https://docs.zespan.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Findings — silent failures with cause, fix and prevention

> Every silent failure Zespan finds in your traces, with the plain cause, the fix, the evidence, where it broke, and how to prevent it. On the trace page and in one project list.

A **finding** is a silent failure Zespan found by checking a trace against what is stored for it: an answer that is not valid JSON, a tool that was called but is not defined, a total that does not add up. Nothing threw, so nothing showed in your logs.

> [!NOTE]
>
> Findings are off by default in the dashboard and appear when they are turned on for your organization. Self-hosted: build the dashboard with `NEXT_PUBLIC_FINDINGS_UI=1`. What each person may see is decided as described in [Who sees findings](#who-sees-findings).

## Findings on a trace

When a trace has findings, a **Findings on this trace** card sits under the verdict. Each finding shows:

| Part | What it says |
| - | - |
| **Title and tier** | What was found, and how sure Zespan is (see below) |
| **What was seen** | The observation, from the stored spans |
| **Cause** | Why this usually happens, in plain words |
| **Fix** | What to change |
| **Evidence** | The recomputed numbers and short values (such as a status or a field name) the finding rests on, and how many passages of the trace it cites. The passages themselves are not copied |
| **Where it broke** | The layer the failure started in, when the attribution is shown to you. See [Stack layers](https://docs.zespan.com/reference/stack-layers.md) |
| **Prevent** | The written advice, and, when prevention is on, what Zespan can draft and test on your recorded traffic. See [Issues](https://docs.zespan.com/dashboard/issues.md#prevent) |

A trace with no findings shows no card.

## Tiers

| Tier | Meaning |
| - | - |
| **Proven** | Recomputed from the stored spans |
| **Likely** | Rule-based, with one assumption you have not confirmed |
| **Signal** | A pattern worth a look. Evidence, not proof |

A finding marked **Needs review** is one Zespan held back for a person to look at. Only owners and admins see that queue.

## The Findings page

**Findings** in the sidebar lists the project's findings, newest first. Filter by:

* **Agent** (exact name)
* **State** (open or needs review)
* **Check family** (D1 to D7 and the domain packs, named as on [Silent-failure coverage](https://docs.zespan.com/reference/silent-failure-coverage.md))
* **Tier**
* **Time range** (24 hours, 7 days, 30 days)

The page shows up to 100 findings at a time and says so; narrow the filters to see others. Each finding links to its trace.

## Who sees findings

Findings are recorded from the first trace, but they are shown only when the project's detectors are on. While they run in **preview**, owners and admins see them marked **Preview** and everyone else sees nothing. When the detectors are off, nobody sees any.

## Free and paid

Every finding shows its cause, fix and written prevention advice on every plan. Drafting a policy that Zespan tests on your own recorded traffic needs the Pro plan; below it the Prevent section shows what kinds of prevention exist, with no draft content.

## Checks that could not run, and why

A check that needs an input your SDK did not record reports that it **could not run** and names the input, instead of passing. When readiness is enabled for your deployment (self-hosted: `CAPTURE_READINESS=on`), `GET /v1/projects/{id}/traces/{traceId}/functional/unchecked` lists the checks that could not run on a trace, and `GET /v1/projects/{id}/functional/readiness?days=7` shows, for the project, the share of checks that could run (**readiness, not a quality score**), the missing inputs that cost the most, whether capture can fix each one, and what to do. Neither route holds any content. The reasons and what each input needs are listed in [Capture fields](https://docs.zespan.com/reference/capture-fields.md).

## Next steps

* [Issues](https://docs.zespan.com/dashboard/issues.md) — recurring failures grouped from failed and degraded traces
* [Traces](https://docs.zespan.com/dashboard/traces.md#where-it-broke) — the verdict and where it broke
* [Silent-failure coverage](https://docs.zespan.com/reference/silent-failure-coverage.md) — which failures are checked and the check families
* [Stack layers](https://docs.zespan.com/reference/stack-layers.md) — what the layer chip means
* [Policies](https://docs.zespan.com/dashboard/policies.md#policies-zespan-drafted) — where a drafted policy shows its test results


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.