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

> ## Agent Instructions
> StackNext documentation is written for developers using StackNext in a Next.js App Router project. Use the getting-started and guides sections to install and operate the product, and the reference section for CLI, configuration, MCP and package surfaces. Version-matched package API reference ships inside each npm package under node_modules/@stacknext/<package>/docs/ and is preferred over this site for installed-version APIs. Diagnostic findings are evidence, not confirmed root causes; regression comparisons are deterministic and report-only. Contributor and repository-maintenance documentation is not part of this site.

# Diagnostics

> The six deterministic Next.js rules, finding statuses, evidence and limits behind every StackNext diagnostic.

StackNext rebuilds a deterministic diagnostic report from the current sample.
The same report is available in the dashboard, `stacknext diagnose`, JSON
export, the read-only MCP tools and the Agent Skill.

Diagnostics never call a model, run SQL, read source files or change your code.

## The six rules

| Rule | Category | What it observes | Status |
| - | - | - | - |
| `n-plus-one-queries` | `database` | The same normalized SQL shape repeated within one trace, aggregated by canonical route across traces | `possible` |
| `slow-request` | `performance` | Requests above `slowRequestMs`, grouped by method and route | `observed` |
| `slow-span` | `performance` | A non-root span whose self time crosses its category threshold | `observed` |
| `repeated-external-http` | `http` | The same normalized external endpoint called repeatedly in one trace, aggregated by route | `possible` |
| `error-fingerprint` | `errors` | Single or repeated errors grouped by canonical route and normalized signature | `observed` |
| `server-error-response` | `errors` | A 5xx request root without a correlated non-control-flow error | `observed` |

These are conservative heuristics. They do not prove an ORM bug, a causal
bottleneck, a retry policy problem or a shared error cause. Read the evidence,
verification steps and limitations on each finding.

> [!WARNING]
>
> A finding is evidence, never a confirmed root cause. Verify it in the trace
> before you change code.

![Diagnostics findings view listing error and warning findings with route, rule, status and evidence](https://mintcdn.com/stack-next/wvbZ0Zo0GO0UM1X7/screenshots/diagnostics.png?fit=max\&auto=format\&n=wvbZ0Zo0GO0UM1X7\&q=85\&s=cbe6c07d1d2b1715665fc8ef429e7535)

![Diagnostics findings view listing error and warning findings with route, rule, status and evidence](https://mintcdn.com/stack-next/wvbZ0Zo0GO0UM1X7/screenshots/diagnostics-dark.png?fit=max\&auto=format\&n=wvbZ0Zo0GO0UM1X7\&q=85\&s=c958724a094136c5eb3d78e85d7c7008)

## Read a finding

A finding contains:

* a deterministic `diag-` id for the current sample;
* the rule, category, severity and status;
* the affected route, time window and trace count;
* a fingerprint of the normalized evidence;
* bounded evidence such as slow-span contributors, trace occurrences, error
  occurrences, query shapes or Next.js phases;
* verification steps and limitations;
* a reference to a related trace when one is available.

Statuses mean:

* `possible` — the pattern is consistent with a problem.
* `observed` — the evidence was measured directly.
* `insufficient-evidence` — the sample cannot support a conclusion.

> [!NOTE]
>
> Severity is separate from status. A high-severity finding still needs
> verification, and a capped report (`maxFindings`) is not a complete inventory.

## CLI

```bash theme={null}
pnpm exec stacknext diagnose
pnpm exec stacknext diagnose --category database
pnpm exec stacknext diagnose --severity warning
pnpm exec stacknext diagnose --trace-id <trace-id>
pnpm exec stacknext diagnose --id <diagnostic-id> --json
```

The report includes the sample window, counts, notes and limitations. A finding
id is deterministic for its evidence but is not a durable database key.

## Dashboard and MCP

The dashboard `/diagnostics` page lists findings and `/diagnostics/:id` shows
one finding with its evidence and related trace.

In MCP clients:

* `stacknext_list_diagnostics` filters by category, severity, status, rule,
  route, trace id, time, query and pagination.
* `stacknext_get_diagnostic` returns one finding plus bounded evidence and a
  related trace reference.

`get_trace` also returns diagnostic references, but they are pointers. Call
`stacknext_get_diagnostic` for the evidence. The MCP server is read-only and
cannot create, acknowledge or delete findings.

## What diagnostics cannot do

* Execute SQL or `EXPLAIN`, inspect source code or recommend indexes.
* Detect long-term anomalies or alert.
* Call an LLM or external service.
* Turn `not-observed` coverage into proof that a feature is broken.
* Establish causality or statistical significance.

## Related

* [Runtime evidence](https://docs.stacknext.space/guides/runtime-evidence.md)
* [Instrumentation coverage](https://docs.stacknext.space/instrumentation-coverage.md)
* [Configuration](https://docs.stacknext.space/reference/configuration.md)
* [Limitations](https://docs.stacknext.space/limitations.md)


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