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

# Troubleshoot a Factory run

> Diagnose missed GitHub events, waits, provider problems and failed stages without losing work.

Start at **Inbox → Waiting on you**, then inspect the run and its latest stage. A stage can wait
legitimately without a live agent; don't cancel until you know what it's waiting for.

```bash theme={null}
architech factory runs show "$RUN_ID" --json
architech factory escalations list --json
```

## A GitHub action did not take effect

> [accordion] An issue was not picked up
>
> Check that the Factory is enabled and the open issue is on the bound board, out of Triage, and
> not held. Ordinary pickup needs all pickup labels. A configured fast-lane label trigger uses its
> own label instead; the Factory still checks who applied it before using it to approve a plan. A GitHub Project owned by a personal account can't be bound to a Cloud
> Factory. Use an organization-owned Project instead. A queue can also mean that active-run capacity
> is full.

> [accordion] A label, review or comment was ignored
>
> Check the gate, the run's pinned label names, and [who may approve](https://docs.mutagent.io/factory/gates.md#who-can-decide).
> Board events supply pickup, gate labels and item comments; the PR review event comes through the
> GitHub App and does not depend on a card move. A boardless PR may not have a board label or comment
> route. A plain PR comment doesn't approve or request changes.
>
> ```bash theme={null}
> mutagent gateway doctor --json
> mutagent gateway events --follow --json
> ```
>
> Check whether a new GitHub event was delivered. If the gate is still pending, use the exact
> `architech factory runs approve` command shown in the Inbox to avoid relying on GitHub delivery.
> `GATE_NOT_PENDING` means the specified gate isn't waiting. Inspect the run again; the default
> pipeline does not wait for a `check` gate.

> [accordion] An approved PR hasn't merged
>
> Check for holds on the PR, parent issue and sub-item. Then check the merge preset, current head,
> CI and whether GitHub reports a conflict. [PR approval and merge authority](https://docs.mutagent.io/factory/gates.md#stop-or-allow-land)
> are separate. A newer push invalidates review evidence for the previous head.

## A stage is waiting or quiet

| What you see | What to do |
| - | - |
| Review waiting on CI | Check CI on the PR's current head. `runs show` can display this wait even before a review session starts. |
| Queued for a sandbox or subscription slot | Wait for capacity unless the run reports a new problem. A queue isn't a request to retry. |
| Budget paused | Check the ledger and the cap named in the run. Day usage can clear with the next day; pushing a new limit will not change this run's pinned limit. |
| Model unavailable, or provider sign-in required | Check the exact model, harness, provider authorization and effort configured in the run's workspace. Reconnect the provider if the prompt asks you to, then follow the offered action. |
| Quiet work session | In the default session mode, a work session can park while idle and wake when a later stage or answer needs it. Check for a pending gate or escalation. |
| Config change didn't reach the run | Compare the run's pinned version with the active Factory version. [Sync the file](https://docs.mutagent.io/factory/operating.md#keep-configuration-in-step) for future runs. |

## Retry, skip or roll back

Read the stopped stage's question and pick an offered action, not a generic retry:

* **Retry the stage** retries the stopped work. **Cancel the run** ends the run.
* **Skip this sub-item**, when offered, closes that part without a PR and lets the rest proceed.
* **Resume the session**, when offered for a provider stoppage, continues the same session.
* **Roll back**, when offered, restores the last complete checkpoint. Work after it is lost.

```bash theme={null}
architech factory escalations answer "$ESCALATION_ID" "Retry the stage" --json
```

For a conflict that needs your judgment, review the named files and fix it on the PR branch as
appropriate before following the question's retry instructions. Don't change a base branch to
silence the error.

## Recover work the App could not push

Read the escalation before using its download or Git instructions. A valid checksum and a
successful `git bundle verify` do **not** tell you whether a bundle contains publishable source.

> [!WARNING]
>
> **Never push the artifact commit** from a workflow patch-artifact bundle. Its commit holds
> patch files, not the recovered source changes.

### Committed-work recovery

Use this path only when the escalation explicitly gives a **source commit to publish** and its
destination branch. If it says the commit is already on the remote, don't publish it again.
If the remote state could not be checked, check the named branch first.

In your clone, follow the escalation's download command. Compare the bundle's SHA-256 checksum
with the value in the escalation and run `git bundle verify` as instructed. Stop if the checksum
is different or verification fails. Then use the escalation's fetch command for the exact
source commit SHA it names.

Only after the fetch succeeds, check that `origin` points to the correct repository and that the
source SHA and destination branch match the escalation. Use the exact push command from the escalation
with your authorized account; do not force-push.

### Workflow patch handoff

The handoff can supply patches inline or in a patch-artifact bundle. Follow the instructions to
extract and inspect the diffs and recover any missing source. If the remote already matches the
expected complete tree, no patch is needed. Otherwise, reconstruct only the named paths at the
stated base, apply the required patches, and commit and publish the resulting **source** using an
account authorized to push workflow changes. Do not push the artifact commit or use the Factory
App to publish workflows.

When the named branch contains the recovered work, select the offered option confirming publication.
For a workflow handoff, the Factory verifies the remote contents and preserved code. If you don't
intend to publish, read the alternative options before answering.


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