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

# Troubleshoot pipelines with Maia AI Agents

export const Activity = () => <>the <strong>Activity</strong> icon <span style={{
  whiteSpace: "nowrap"
}}><img src="/images/global-nav/activity.png" width="20" height="20" style={{
  verticalAlign: "text-bottom",
  display: "inline",
  margin: "0 1px"
}} /></span></>;

export const maia_agents = "Maia AI Agents";

export const designer = "Designer";

export const maia = "Maia";

{maia_agents} provide intelligent pipeline monitoring and troubleshooting capabilities that help you identify and resolve issues quickly. This guide covers how to use {maia_agents} for anomaly detection, root cause analysis, and guided pipeline recovery.

***

## Accessing pipeline runs

To view your pipeline execution history, click <Activity />, then **Pipeline Runs**. Here, you can view a list of recent pipeline executions, along with their status (**Success** or **Failed**), and any anomaly indicators.

<img src="https://mintcdn.com/matillion/I06T4ygCZYYqgb0_/images/using-maia-for-root-cause-analysis/using-maia-for-root-cause-analysis-01.png?fit=max&auto=format&n=I06T4ygCZYYqgb0_&q=85&s=0cf0aa2cff687a51721eb9f04820dc02" alt="Pipeline runs activity" width="2512" height="668" data-path="images/using-maia-for-root-cause-analysis/using-maia-for-root-cause-analysis-01.png" />

***

## Pipeline recovery with Maia

When a scheduled or API-triggered executed pipeline run fails, {maia} generates a [root cause analysis](#root-cause-analysis). If {maia} identifies a fix for the problem, you can then use the [Fix with {maia}](#fix-with-maia) feature to recover your pipeline.

### Root cause analysis

When a pipeline fails, {maia} automatically analyzes the error and provides a context-aware root cause analysis to help you understand what went wrong.

To view the root cause analysis:

1. In **Pipeline Runs**, click the name of any pipeline with a **Failed** status.
2. On the **Pipeline run details** page, click **See more** in the **Troubleshoot with Maia** card.

As part of this root cause analysis, {maia} automatically:

* Analyzes failures at every level of your pipeline, including inside iterators and orchestration steps
* Captures pipeline-level failures such as specific SQL errors
* Includes warning-level runner task logs to provide context on the lead-up to the failure
* Identifies the exact cause of the error, not necessarily where it occurred
* Summarizes each issue in plain language, including a category and an indication of whether it's fixable within your pipeline
* Suggests recommended fixes

For example, let's say a renamed column in a Salesforce source caused a SQL compilation error in a downstream extract step. {maia} will identify the schema change in the source as the root cause—not the SQL step where the error appeared—and suggest updating the column reference to match the new name.

### Fix with Maia

{maia} can assist you in applying any recommended fixes identified during the root cause analysis. It uses contextual awareness of the executed pipeline's codebase and history to apply changes accurately and efficiently. The proposed fix targets the originating component—the root cause identified during analysis—rather than the step where the error surfaced. Review the changes before committing to ensure that you are happy with the applied fix.

<Note>
  **Fix with Maia** is only available for scheduled or API-triggered pipeline executions.
</Note>

If {maia_agents} identify a recommended fix, a **Fix with Maia** button will appear in the **Troubleshoot with Maia** card. To recover your pipeline with {maia_agents}:

1. Click **Fix with Maia** to open the dialog.
2. Enter the following details to create a new branch for applying fixes to your pipeline:
   * **Branch Name:** Provide a unique name for the new working branch where the fixes will be applied.
   * **Select base branch:** Choose the source branch from which the new branch will be created. We recommend branching from the `main` branch. {maia_agents} highlight the most relevant branch as "suggested" based on your commit and publish history. You can select a different branch if required.
   * **Select environment:** Choose the environment where the new branch will be deployed. {maia_agents} automatically select the environment in which the failure occurred by default. You can choose a different environment if required.
3. Click **Get started** to proceed.

You will be redirected to the {designer} canvas in the newly created branch, where {maia_agents} will instantly begin working in the background to apply the necessary changes to resolve the fault. After {maia_agents} apply the fixes:

1. Compare the changes {maia_agents} have made against the original code.
2. Complete the fix by committing the changes, pushing the local changes to the remote repository, and publishing your pipeline. For more information about using source control, read [Git in {designer}](/docs/guides/git-overview).

***

## Anomaly detection

{maia_agents} automatically monitor your scheduled pipeline runs and flag significant deviations from expected behavior. This helps you detect potential issues before they become failures.

{maia_agents} use statistical modeling to compare each scheduled pipeline run against historical trends. When execution time falls significantly outside the expected range, {maia_agents} flag the run as an anomaly. Anomaly detection currently provides visual indicators only—no alerts are triggered (such as email notifications).

<Note>
  {maia_agents} require at least 10 prior scheduled runs of the same pipeline to establish a reliable trend for anomaly detection.
</Note>

### Anomaly indicators

In the **Pipeline Runs** dashboard, anomalies are displayed with:

* **Red arrows** (up/down) highlighting anomalies next to duration metrics
* **Tooltips** with details when you hover over the indicator (for example: "7.8% longer than expected based on recent runs")
* **Anomalies section** listing all detected anomalies for the run

<img src="https://mintcdn.com/matillion/I06T4ygCZYYqgb0_/images/using-maia-for-anomaly-detection/using-maia-for-anomaly-detection-01.png?fit=max&auto=format&n=I06T4ygCZYYqgb0_&q=85&s=c0803dd0393556dd0f628bcf9bccc616" alt="Anomaly flag showing 7.8% longer" width="1306" height="129" data-path="images/using-maia-for-anomaly-detection/using-maia-for-anomaly-detection-01.png" />

### Common anomaly scenarios

| Scenario                        | Example                                       | Anomaly type          |
| ------------------------------- | --------------------------------------------- | --------------------- |
| Infrastructure performance      | Load times spike due to backend slowness      | Execution time higher |
| Optimization or refactoring     | Code change makes execution faster than usual | Execution time lower  |
| Source data changes             | Upstream table has significantly more data    | Execution time higher |
| Schema or configuration updates | Business logic change affects processing      | Execution time varies |