> ## 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.

# Errors and exit codes

> What the Mutagent CLI prints when a command fails, the JSON error object, the exit codes, and why delete commands need --force.

When a command fails, the CLI tells you three things: what went wrong, the command that fixes it, and
an exit code that says what kind of failure it was. A script can branch on the exit code, and a
coding agent can read the fix from the JSON output.

## A failing command

Run a command without signing in:

```bash theme={null}
mutagent providers list
echo "exit code: $?"
```

```text theme={null}
Error: Not signed in. Run: mutagent login

Authentication required. Options:
  Interactive:     mutagent login --browser
  Non-interactive: export MUTAGENT_API_KEY=<your-key>
  CI/CD:           export MUTAGENT_API_KEY=<key>, then: mutagent login --json
exit code: 3
```

The error goes to stderr. `mutagent login` and `mutagent auth login` are the same command.

The same command with `--json`:

```bash theme={null}
mutagent providers list --json
```

```json theme={null}
{
  "success": false,
  "error": "Not signed in. Run: mutagent login",
  "code": "AUTH_REQUIRED",
  "suggestedAction": "Run: mutagent login --browser",
  "remediation": {
    "interactive": "mutagent login --browser",
    "nonInteractive": "export MUTAGENT_API_KEY=<your-key>",
    "ciCd": "export MUTAGENT_API_KEY=<key>, then: mutagent login --json"
  },
  "_agentGuidance": {
    "helpCommand": "mutagent providers list --help",
    "suggestion": "Run: mutagent login --browser",
    "fix": ["mutagent login --browser"],
    "notes": [],
    "escalate": "Signing in needs a person at a browser, or a MUTAGENT_API_KEY from them."
  }
}
```

## The JSON error object

With `--json`, a failed command prints one JSON object on stdout. Every one has these fields:

| Field | What it is |
| - | - |
| `success` | Always `false` for an error. |
| `error` | What went wrong, in one sentence. |
| `code` | A stable code for the kind of failure, such as `AUTH_REQUIRED` or `WORKSPACE_REQUIRED`. Branch on this, not on the text. |
| `suggestedAction` | The command or step that fixes it. When there is none, it names the command's `--help`. |
| `_agentGuidance` | Help for coding agents: `helpCommand` (the `--help` of the command that failed), `fix` (commands to run), `notes` (steps that are not a single command), and `escalate` when a person has to act, such as signing in or confirming a delete. |

Sign-in, workspace and access errors also carry `remediation`: the commands that fix each case.

Another example, a workspace name that does not exist:

```bash theme={null}
mutagent providers list --workspace no-such-workspace --json
```

```json theme={null}
{
  "success": false,
  "error": "No workspace \"no-such-workspace\" among your workspaces in acme. See: mutagent workspaces list",
  "code": "TENANCY_DENIED",
  "suggestedAction": "mutagent workspaces list",
  "_agentGuidance": {
    "helpCommand": "mutagent providers list --help",
    "suggestion": "mutagent workspaces list",
    "fix": ["mutagent workspaces list"],
    "notes": []
  }
}
```

## Exit codes

Every command uses the same four exit codes. Under `--json`, `success` is `true` exactly when the
exit code is 0.

| Code | Meaning | Common codes | What to do |
| - | - | - | - |
| 0 | Success. | | |
| 1 | The command failed or was refused: the server said no, a name was not found, an argument or option was wrong, the API could not be reached, or a delete was not confirmed. | `NOT_FOUND`, `VALIDATION_ERROR`, `UNKNOWN_OPTION`, `TENANCY_DENIED`, `ORG_MISMATCH`, `CONFIRMATION_REQUIRED`, `NETWORK_ERROR`, `RATE_LIMIT_ERROR`, `API_<status>` (except `API_401`) | Read `error` and `suggestedAction`. |
| 2 | Your API key expired, was revoked, or is not a valid Mutagent key. | `AUTH_EXPIRED`, `INVALID_API_KEY`, `FOREIGN_API_KEY`, `API_401` | Run `mutagent login` again, or set a valid `MUTAGENT_API_KEY`. |
| 3 | You are not signed in, or no workspace is selected. | `AUTH_REQUIRED`, `WORKSPACE_REQUIRED` | Run `mutagent login`, then `mutagent workspaces use <name>`. |

`mutagent` on its own, or a command group on its own such as `mutagent env`, prints its help and
exits 0.

Commands that run something in a cloud sandbox pass its exit status through instead:
`mutagent helix` runs, `helix doctor` and `helix smoke` exit with Helix's own exit status. See
[Run a task](/helix/cloud/agent-runs#exit-status).

## Delete commands need --force

A command that deletes something never asks "are you sure?". It refuses unless you pass `--force`
(or `-f`), and it deletes nothing:

```bash theme={null}
mutagent env delete staging
```

```text theme={null}
Error: Deleting Environment staging (its secrets are removed with it) requires --force. Nothing was sent.
Suggestion: Run: mutagent env delete staging --force
```

The exit code is 1 and the error code is `CONFIRMATION_REQUIRED`. Run it again with `--force` once
you are sure:

```bash theme={null}
mutagent env delete staging --force
```

This way a script or a coding agent can never hang on a question it cannot answer, and a delete
always happens on purpose. With `--json`, the error's `_agentGuidance.escalate` tells a coding agent
to confirm with you before it runs the command again with `--force`.

The rule holds in every mode: in a terminal, with `--json`, and with `--non-interactive`. It covers
every command that deletes, removes or stops something, including `env delete`, `env unset`,
`env set --replace`, `providers delete`, `sandbox delete`, `helix session signal`, `agent retire`,
`reports retract`, `integrations sources remove`, and the gateway's `disconnect`, `repos unlink`,
`triggers delete`, `routines delete` and `runs cancel`.
The gateway, `reports` and `integrations` commands also accept `--yes` in place of `--force`.

List and delete commands have one name each, with a short alias: `list` also answers to `ls`, and
`delete` to `rm`.

## Common errors

<AccordionGroup>
  <Accordion title="AUTH_REQUIRED (exit 3)">
    You are not signed in on this machine and `MUTAGENT_API_KEY` is not set. Run `mutagent login`.
    In CI, set `MUTAGENT_API_KEY` to an API key. See [API keys](/quickstart/api-keys).
  </Accordion>

  <Accordion title="AUTH_EXPIRED, INVALID_API_KEY or FOREIGN_API_KEY (exit 2)">
    Your saved key expired or was revoked, or the key you passed is not a Mutagent key. Mutagent
    keys start with `mg_live_`. Run `mutagent login` again, or set a valid `MUTAGENT_API_KEY`.
  </Accordion>

  <Accordion title="WORKSPACE_REQUIRED (exit 3)">
    The command works in a workspace and none is selected. Run `mutagent workspaces list`, then
    `mutagent workspaces use <name>`, or pass `--workspace <name>` for one command. With a
    `MUTAGENT_API_KEY` you did not save with `mutagent login`, set `MUTAGENT_WORKSPACE_ID` instead.
  </Accordion>

  <Accordion title="WORKSPACE_FROM_ENV (exit 1)">
    You ran `mutagent workspaces use` with `MUTAGENT_API_KEY` set to a key you did not save with
    `mutagent login`. Such a key has no saved workspace. Pass `--workspace <name-or-id>`, set
    `MUTAGENT_WORKSPACE_ID`, or run `mutagent login --json` once to save the key.
  </Accordion>

  <Accordion title="INTERACTIVE_REQUIRED (exit 1)">
    `mutagent login --json` had no way to sign in: no `MUTAGENT_API_KEY`, no `--browser`, and no
    terminal to ask in. Run `mutagent login --browser --json` and show the printed URL to a person, or
    set `MUTAGENT_API_KEY` and run `mutagent login --json`. See [Sign in](/cli/commands/login).
  </Accordion>

  <Accordion title="TENANCY_DENIED (exit 1)">
    The workspace you named is not one of your workspaces in this organization. Check the name with
    `mutagent workspaces list`.
  </Accordion>

  <Accordion title="ORG_MISMATCH (exit 1)">
    You passed `--org` and your key belongs to another organization. Nothing was sent. To work in
    that organization, sign in to it: `mutagent login --org <slug>`.
  </Accordion>

  <Accordion title="CLOUD_NOT_ENABLED (exit 1)">
    Cloud sandboxes are in early access and not enabled for your account yet. Nothing was started.
    See [Helix Cloud](/helix/cloud/overview).
  </Accordion>
</AccordionGroup>

For errors from cloud runs, such as a missing model, see
[Troubleshooting cloud runs](/helix/cloud/troubleshooting).


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