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.
The RCA agent is currently available as a private preview feature.
Contact support@soda.io to opt in.
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
Usage
The root cause analysis (RCA) agent investigates failing Soda checks from inside your own 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.
Configure your Claude Code with the Soda plugin and connections to the key components of your data stack.
Just paste the Soda Cloud URL of the check failure in your Claude Code to activate the root cause analysis.
rca skill and the coverage check.
How it works
The investigation follows a fixed order:
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.
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.
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.
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. The plugin contains two skills:
/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.
To install the plugin, refer to Install the Soda plugin.
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:
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.
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.
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
majorunless 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.
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 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.
Last updated
Was this helpful?