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

# Debugging an Incident

> Use the Debug feature in Validio to generate sample SQL and investigate the data causing quality incidents.

When investigating individual [incident groups](https://docs.validio.io/v10.1/docs/incidents-and-errors/incidents/incident-details.md), the **Debug** feature generates sample SQL queries from captured incidents, allowing you to investigate the exact data causing quality issues directly in your database. Queries you find useful can be saved against the validator and reused on future incidents. For AI-assisted investigation, see [Root Cause Analysis](https://docs.validio.io/v10.1/docs/incidents-and-errors/root-cause-analysis.md).

![The debug information panel for a data warehouse source, showing the generated query and its results](https://mintcdn.com/validio/h4NQPs1kJwlpB1Yj/images/docs/incidents-and-errors/450-debug-information.png?fit=max\&auto=format\&n=h4NQPs1kJwlpB1Yj\&q=85\&s=5fa7f84a1dd898edb307caa5dd485275)

Debug Information for a Data Warehouse Source

## Prerequisites for debug

To use the Debug feature, ensure the following requirements are met:

* **Source type**: Debug is available for data warehouse and query engine sources where Validio uses SQL pushdown for validation.
* **Permissions**: Your role must have the following permissions in the namespace. See [Managing Roles](https://docs.validio.io/v10.1/docs/access-and-settings/settings/managing-roles.md).

| Permission | What it allows |
| - | - |
| `incidents:WRITE` | Opening Debug, and every action inside it |
| `sqlExecution:WRITE` | Opening Debug, loading sample records, and exporting them |
| `validators:READ` | Seeing the validator's saved queries |
| `validators:WRITE` | Saving, updating, renaming, deleting, and setting a default query |

## How debug works

The **Debug** feature is available where individual incidents are listed, such as in a details page for incident groups, and provides:

* **Automatically generated SQL**: Validio generates a SQL query that reproduces the data quality incidents. The query,
  * Filters data down to the specific Window and Segment where the incident occurred. It does this using placeholders — the time range and segment appear as `{{ validio_... }}` rather than as fixed values, and Validio fills them in when the query runs. See [Debug Query Syntax](https://docs.validio.io/v10.1/docs/incidents-and-errors/incidents/debug-query-syntax.md).
  * Orders records based on how far away they are from being allowed, returning the most prominent outliers at the top.

> [!NOTE]
>
> **Troubleshooting Outliers**
>
> Although outliers are not the only cause of incidents, they are a good starting point for troubleshooting.

* **Sample data generation**: Use **Run** for Validio to automatically generate sample rows from the detected incidents to help you troubleshoot.
* **Query customization**: Modify the generated query to explore different aspects of the problem. The query actions sit above the editor. If needed, **Reset** removes your edits and returns to the original generated SQL.
* **Copy support**: Copy the query to run in your preferred database tools for deeper analysis.
* **Reusable queries**: Save a query you want to run again, and pick it up on any future incident for the same validator. See [Saving and Reusing a Debug Query](#saving-and-reusing-a-debug-query).

## Saving and reusing a debug query

A saved debug query belongs to the validator, not to the incident you saved it from. Once saved, it is available on every incident for that validator, to anyone with `validators:READ` in the namespace.

To save a query:

1. Open **Debug** on an incident and edit the SQL until it returns what you need.
2. Select **Save** and give the query a name.

A query keeping its window placeholders re-binds to whichever incident you open it from; one with the timestamps written in returns the same range every time. Validio saves either kind — see [Debug Query Syntax](https://docs.validio.io/v10.1/docs/incidents-and-errors/incidents/debug-query-syntax.md). If **Save** is unavailable, hover it to see why.

To reuse a saved query:

1. Open **Debug** on any incident for the same validator.
2. Choose the query from the **Queries** picker above the editor.
3. Select **Run**. Any placeholders bind to the incident you are currently viewing.

To change a saved query, select it, edit the SQL, and choose **Save** again. The name field is pre-filled with the query's current name, so saving over a query and renaming it are the same step. **Save** is unavailable until you have actually changed something.

### Setting a default query

One of a validator's saved queries can be its default. When a validator has a default query, opening **Debug** on any of its incidents loads that query instead of the freshly generated one — useful when a validator has a known investigation path you want everyone to start from.

To set one, open the **Queries** picker and choose the bookmark action on that query's row. Setting a new default clears the previous one, so a validator never has more than one.

### Renaming and deleting

To rename a saved query, select it and choose **Save** — the name field opens pre-filled, and the new name replaces the old one.

To delete one, open the **Queries** picker and choose the delete action on that query's row. Deleting asks for confirmation first, then removes the query for everyone in the namespace. A validator's saved queries are deleted along with the validator itself.

## Viewing the executed SQL

Sample records are produced by the query with its placeholders expanded, which is not quite the SQL shown in the editor. To see what actually ran, expand **Executed SQL** beneath the sample records.

The panel reflects the samples currently on screen rather than what is in the editor. If you edit the query after loading samples, both the records and the executed SQL are dimmed to show they are out of date, and running the query again refreshes them.