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

# Run troubleshooting

> Interpret Gauge Agents run states, inspect missing verdicts, and decide when to try again.

A run's execution status and its eval verdict answer different questions. **Succeeded** means the session finished successfully; it does not necessarily mean it passed every criterion. Judging and analytics can finish after execution.

## Read the status

| Status                 | Meaning and next step                                                                                         |
| ---------------------- | ------------------------------------------------------------------------------------------------------------- |
| Queued                 | The run is waiting to start. Check this run before submitting the task again.                                 |
| Claimed / Provisioning | Gauge is preparing the execution environment. If it remains here unexpectedly, share the run ID with support. |
| Running                | The coding session is active. Open its events or use `gauge runs watch`.                                      |
| Succeeded              | Inspect the session, diff, and judged criteria. A completed session can still fail its eval.                  |
| Failed                 | Inspect the exit reason and logs for setup, provider, or execution errors before launching another run.       |
| Timed out              | The run reached an execution limit. Inspect its progress and consider a smaller task or an adjusted scenario. |
| Canceled               | Cancellation ended the run. Canceled runs do not receive a run-credit refund.                                 |

Failed or timed-out runs receive a run-credit refund. A successfully executed session that fails an eval criterion does not count as an execution failure. See [Billing and credits](/agents/guides/billing) for how charges are calculated.

## Inspect a run

Replace `<run-id>` with the ID from the run list:

```bash theme={null}
gauge runs get <run-id>
gauge runs logs <run-id>
gauge runs diff <run-id>
gauge runs insight <run-id>
```

`logs` returns events available so far. A research task may make no repository changes, so an empty diff alone is not a failure.

If a run has finished but its insight or verdict is pending, allow the analysis to complete. Pending or failed judging does not enter the eval pass-rate denominator. Check the judged-run count as well as the percentage.

## When no runs are created

1. Check the organization with `gauge status`.
2. Inspect the eval with `gauge evals get <eval-id>` and its attached scenarios with `gauge evals scenarios list <eval-id>`.
3. Check `gauge billing status` for balance and workload eligibility.
4. If a provider key is required, resolve that connection before trying again. See [Configure a scenario](/agents/guides/configure-a-scenario).

An eval without scenarios will not produce recurring runs. A one-off scenario can be supplied for a manual run, as shown in the [quickstart](/agents/quickstart).

## Retry deliberately

Read the original run's status before launching a replacement, especially after a network timeout. A new launch can create additional billable work. Fix the cause first, then rerun the same task and criteria to make the comparison useful.

For persistent failures, contact [support@withgauge.com](mailto:support@withgauge.com) with the organization, run/eval link, status, and visible error. Do not include provider keys or credentials.