> For the complete documentation index, see [llms.txt](https://docs.soda.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.soda.io/soda-ai/rca-agent.md).

# Root cause analysis (RCA) agent

Let your own Claude Code investigate a failing Soda check, trace it to its root cause, assess impact and publish the analysis onto a Soda Cloud incident.

{% hint style="success" %}
The RCA agent is currently available as a [**private preview** feature](/reference/documentation-access-and-licensing/release-stages.md#private-preview).

Contact <support@soda.io> to opt in.
{% endhint %}

The root cause analysis automates the tedious process of digging into various tools to investigate a failing Soda check. Instead of:

* Analyzing what exactly failed
* Hypothesizing of what the cause might be
* Checking neighboring checks and datasets
* Navigating upstream to find the root cause
* Inspecting the code and orchestration logs
* Find the root cause,

**the agent** will use all the connected tools to **find the root cause of the problem**.

Once the root cause is found, the agent can:

* **Analyze** the impact of the problem
* **Propose** a fix
* **Find people** to notify
* **Create an incident** with a RCA report in Soda Cloud (connected to JIRA or ServiceNow)

***

**Watch a demo to see the RCA Agent in action**

{% embed url="<https://www.youtube.com/watch?v=pITlvRyFoIo>" %}

## Usage

The root cause analysis (RCA) agent **investigates failing Soda checks** from inside your own [Claude Code](https://claude.com/claude-code).

Start Claude Code and paste the link of a failing check, copied from the check page in Soda Cloud. Claude Code recognizes the failing check and starts the `/rca` skill. You can also type `/rca` yourself, followed by a description of the problem, such as a dataset that looks stale.

<figure><img src="https://1123167021-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FA2PmHkO5cBgeRPdiPPOG%2Fuploads%2Fgit-blob-691b02eef91e05b0b63e3f8692409900e04861e4%2Frca-agent-failing-check.png?alt=media" alt=""><figcaption><p>A failing check in Soda Cloud: copy the link from this page.</p></figcaption></figure>

Configure your Claude Code with the Soda plugin and connections to the key components of your data stack.

<figure><img src="https://1123167021-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FA2PmHkO5cBgeRPdiPPOG%2Fuploads%2Fgit-blob-8555cd5c1447ef87d4a5ff3ea90b3b3b405d7947%2Frca-agent-mcp-servers.png?alt=media" alt=""><figcaption><p>The Soda plugin delivers Soda MCP and the RCA skill next to your other MCP servers.</p></figcaption></figure>

Just paste the Soda Cloud URL of the check failure in your Claude Code to activate the root cause analysis.

<figure><img src="https://1123167021-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FA2PmHkO5cBgeRPdiPPOG%2Fuploads%2Fgit-blob-a20e35fb80912ae5759c0dbfa0fee0ef5663d98f%2Frca-agent-claude-code-start.png?alt=media" alt=""><figcaption><p>The pasted link starts the <code>rca</code> skill and the coverage check.</p></figcaption></figure>

<figure><img src="https://1123167021-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FA2PmHkO5cBgeRPdiPPOG%2Fuploads%2Fgit-blob-590eccb2dd88a37a30251443144eef176fe7b6cd%2Frca-agent-root-cause-report.png?alt=media" alt=""><figcaption><p>The report opens with the root cause: a commit that divided contract values by 100 twice.</p></figcaption></figure>

<figure><img src="https://1123167021-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FA2PmHkO5cBgeRPdiPPOG%2Fuploads%2Fgit-blob-78a6396d2517f9fb94e4b59efee88119fd41d920%2Frca-agent-follow-up-actions.png?alt=media" alt=""><figcaption><p>The follow-up picker after the report, with all four actions selected.</p></figcaption></figure>

<figure><img src="https://1123167021-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FA2PmHkO5cBgeRPdiPPOG%2Fuploads%2Fgit-blob-468df9ccd2bc38aaa14847cb8c08d1e435125def%2Frca-agent-incident-lineage.png?alt=media" alt=""><figcaption><p>The RCA report on the incident page in Soda Cloud, showing the lineage and the suggested remediation.</p></figcaption></figure>

## How it works

The investigation follows a fixed order:

1. **Triage.** The agent uses Soda MCP to find every failing check and notes each check's dataset, type, and last evaluation time. Related failures are evidence, so it looks at all of them before theorizing about any one.
2. **Orchestrator.** It lists the recent runs of the pipeline that loads those datasets and reads the task logs rather than only the task states. A green run can still skip its work.
3. **Upstream trace.** It finds the deployed code version in the logs and investigates that exact commit. It queries the warehouse for row counts and load timestamps to find where fresh data upstream turns into stale data downstream, and reads the transformation project to see which models were built or skipped.
4. **Lineage.** It walks upstream from the failing check's dataset to the first dataset that is already wrong. Lineage comes from the first available source in this order: the warehouse's own lineage, a catalog, the transformation project's model graph, and finally the pipeline code.

Every claim in the result is grounded in evidence the agent gathered: tool output, log lines, query results, or commits. The agent does not search your filesystem for projects nobody mentioned. It works with the tools connected to the session and the repositories its evidence points at.

The agent is delivered as the **Soda plugin** for Claude Code, together with [Soda MCP](/soda-ai/soda-mcp.md). The plugin contains two skills:

| Skill              | What it does                                                                                                       |
| ------------------ | ------------------------------------------------------------------------------------------------------------------ |
| `/rca`             | Investigates one or more failing checks or contract verifications and reports the root cause.                      |
| `/create-incident` | Creates an incident in Soda Cloud linked to the failing check results. Usually runs as the closing step of an RCA. |

{% hint style="info" %}
Creating incidents and publishing RCA reports from the agent **requires the incident RCA feature to be enabled** for your organization. Contact <support@soda.io> to enable it.
{% endhint %}

> To install the plugin, refer to [Install the Soda plugin](/soda-ai/rca-agent/install-the-soda-plugin.md).

## Tool coverage

The agent investigates with the tools connected to your Claude Code session. Soda MCP, installed with the plugin, tells it which checks are failing. Everything else comes from MCP servers for your own stack:

| Capability     | Question it answers                                   | Examples                                                              |
| -------------- | ----------------------------------------------------- | --------------------------------------------------------------------- |
| Quality signal | Which checks are failing                              | Soda MCP, installed with the plugin                                   |
| Orchestration  | Whether the pipeline run actually did the work        | Airflow, Dagster, Prefect                                             |
| Warehouse      | Whether the data is wrong, and where freshness breaks | Snowflake, Databricks, BigQuery, PostgreSQL, Redshift                 |
| Transformation | Which model produces the bad column                   | dbt, SQLMesh                                                          |
| Code history   | Which change caused it                                | The `gh` and `git` CLIs, or a GitHub, GitLab, or Bitbucket MCP server |

The agent runs with whatever is connected. A capability it cannot reach becomes part of the report, and the agent offers to help you close the gap.

> To connect your orchestrator, warehouse, and transformation project, refer to [Connect your data stack](/soda-ai/rca-agent/connect-your-data-stack.md).

## The report

The report leads with the finding: what failed and why, in a few sentences. It then gives a table of the failing checks with links to Soda Cloud, the root cause with its evidence trail, and a lineage diagram of the causal path from the root cause to the failing checks, annotated with the offending commit or the timestamps where freshness breaks.

When a capability was not connected, the report closes with what the agent could not check and what it did instead, so you can weigh an analysis that leaned on inference rather than a query.

## Follow-up actions

After the report, the agent asks which follow-up actions to run. You can pick several.

| Action                        | What it does                                                                                                                                                                                                                                         |
| ----------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Analyze impact of the problem | Walks downstream from the root cause and gives a verdict per dataset, decided from the transformation code rather than from dataset names. Calls out datasets whose checks are still green but whose data is wrong, and ends with an impact diagram. |
| Propose fix                   | For a code or configuration cause, the exact revert or edit as a diff with file paths. For bad data, the corrective action: reload, backfill, or quarantine. Includes what must re-run for the checks to go green.                                   |
| Show whom to notify           | Lists the owners of the impacted datasets and data sources from Soda Cloud, plus the author of the offending commit, with what each person needs to do.                                                                                              |
| Create incident               | Creates an incident in Soda Cloud, links the failing check results, and publishes the full RCA report and impact assessment onto the incident page.                                                                                                  |

The agent only proposes fixes. It does not commit to a remote, push, or open a pull request unless you explicitly ask it to.

### Create incident

Selecting **Create incident** is the go-ahead. The agent creates the incident without asking again, using the results of the investigation:

* The incident description is a short plain-text summary of the finding. The full analysis, lineage, and impact assessment are published separately as the RCA report on the incident page.
* Severity is `major` unless you asked for a different one.
* The lead is resolved in this order: the owner of the root cause dataset, the owner of the failing dataset, the owner of the data source, the author of the offending commit, and finally the user whose API key the agent uses. Group responsibilities are skipped, because a group cannot lead an incident.
* Each failing check result can belong to only one incident. If a result is already linked, the agent reports which incident covers it instead of retrying.

When **Create incident** is combined with other actions, it always runs last, so the report it publishes carries the deepened impact assessment and the proposed fix.

The API key the agent uses needs the **Manage incidents** permission on every dataset whose check results are linked.

> To learn how incidents work in Soda Cloud, refer to [Incidents](/manage-issues/incidents.md).

## Limitations

* The plugin runs in Claude Code on macOS, Linux, and Windows inside WSL 2. Native Windows is supported on Windows 11 ARM64. Refer to [Install the Soda plugin](/soda-ai/rca-agent/install-the-soda-plugin.md) for the supported versions.
* The depth of the analysis depends on what is connected. With Soda MCP alone, the agent can triage the failing checks but cannot query your warehouse or read pipeline logs.
* Register warehouse MCP servers read-only. The agent never needs to write, and an investigation must not be able to.
* The agent's findings are grounded in the evidence it can reach, but you remain responsible for reviewing them before acting on them.

***

{% hint style="info" %}
You are **not logged in to Soda** and are viewing the default public documentation. Learn more about [Licensing & documentation access](/reference/documentation-access-and-licensing.md).

If you do have a Soda license, make sure to **log in to Soda Cloud in this same browser**.
{% endhint %}


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://docs.soda.io/soda-ai/rca-agent.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.