Errors and exit codes

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:

mutagent providers list
echo "exit code: $?"

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:

mutagent providers list --json

{
  "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:

mutagent providers list --workspace no-such-workspace --json

{
  "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.

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:

mutagent env delete staging

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:

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

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.

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.

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.

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.

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.

TENANCY_DENIED (exit 1)

The workspace you named is not one of your workspaces in this organization. Check the name with mutagent workspaces list.

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

CLOUD_NOT_ENABLED (exit 1)

Cloud sandboxes are in early access and not enabled for your account yet. Nothing was started. See Helix Cloud.

For errors from cloud runs, such as a missing model, see Troubleshooting cloud runs.

CLI

Account

Workspace

Helix

Setup

Errors and exit codes

A failing command

The JSON error object

Exit codes

Delete commands need —force

Common errors

​A failing command

​The JSON error object

​Exit codes

​Delete commands need —force

​Common errors

A failing command

The JSON error object

Exit codes

Delete commands need —force

Common errors