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

# Troubleshooting cloud runs

> What the errors from mutagent helix mean and what to do: models, launch arguments, sessions, idle sandboxes, Environments, and LLM provider mirroring.

<Note>
  **Early access.** Cloud sessions and managed agent runs are not open to every account yet: we are
  letting accounts in gradually while we test. They run in a cloud sandbox operated by Mutagent, so
  there is nothing to host. A sandbox with nothing to do for 15 minutes stops; send the session a
  message and it wakes up, delivers your message and carries on in the same conversation.
</Note>

Most refusals happen on your machine, before anything starts, and end with exit code 1 and a line
that says what to do instead. Errors returned by the platform include an HTTP status. If a
launch fails after it printed a session reference, the session may still be running: check
`mutagent helix session ls` before you start the task again.

Before a run starts, the CLI's exit codes apply: 0 success, 1 failure (usage errors included), 2 your
Mutagent API key expired or is invalid, 3 not signed in or no workspace. Once a run has started, the
exit code is Helix's own. With `--mode json` or `--mode rpc`, a refused launch is one JSON line on
stderr; run what its `_agentGuidance.fix` names. See [Errors and exit codes](/cli/errors).

## Sign-in and workspace

<AccordionGroup>
  <Accordion title="Not signed in (exit code 3)">
    Run `mutagent login`. Without a browser, set `MUTAGENT_API_KEY` and run `mutagent login --json`.
    A coding agent helping a person runs `mutagent login --browser --json` and shows them the printed
    URL; the CLI waits up to 5 minutes. See [Sign in](/cli/commands/login).
  </Accordion>

  <Accordion title="The key expired or is invalid (exit code 2)">
    Sign in again with `mutagent login`, or set a valid `MUTAGENT_API_KEY`. Mutagent keys start with
    `mg_live_`.
  </Accordion>

  <Accordion title="Cloud sandboxes are not enabled for your account yet">
    Helix Cloud is in early access and is not open to every account yet: we are letting accounts in
    gradually while we test. The launch was refused with code `CLOUD_NOT_ENABLED` and exit code 1,
    and nothing was started. Local Helix, `mutagent agent check`, `pack` and `run` work without it.
  </Accordion>

  <Accordion title="--api-key after mutagent helix is refused">
    After `mutagent helix`, `--api-key` would be read as your Mutagent platform key and sent to the
    platform. Model keys belong to the workspace's [LLM providers](/helix/cloud/setup).
    To pass your Mutagent key, put it before the command, as in
    `mutagent --api-key <mutagent-key> helix -p "<task>"`, or set `MUTAGENT_API_KEY`.
  </Accordion>

  <Accordion title="--endpoint after mutagent helix is refused">
    After `mutagent helix`, `--endpoint` would be read as the Mutagent platform address, and your
    platform key would be sent there. Put it before the command, as in
    `mutagent --endpoint <url> helix …`, or set `MUTAGENT_ENDPOINT`. An LLM provider's endpoint is
    part of that LLM provider's configuration.
  </Accordion>

  <Accordion title="A workspace is required">
    ```bash theme={null}
    mutagent workspaces list
    mutagent workspaces use <workspace-name>
    ```

    To use another workspace for one command, pass `--workspace <name-or-id>` before the command.
    See [Sign-in and workspaces](/cli/commands/login).
  </Accordion>

  <Accordion title="Access to the workspace is refused">
    Check the selected workspace with `mutagent workspaces current`. A session in another workspace is reported as not
    found.
  </Accordion>
</AccordionGroup>

## Models

<AccordionGroup>
  <Accordion title="The launch is refused with HTTP 428">
    The error code is `NO_PROVIDER_CONFIGURED`. Nothing was started. Read the error message to see
    which of the two causes applies:

    1. **No default model.** The run named no `--model`, and `mutagent helix models` shows
       "No default set". Pass `--model <provider/model>` for this run, or set a default:
       `mutagent helix models default <provider/model> [fallback …]`. Any workspace member can set
       it.
    2. **The model's LLM provider is not configured** ("Model X needs LLM provider Y, which this
       workspace has not configured"). Add the provider:
       `mutagent providers add --provider <type> --name <name> --api-key-stdin`, or copy your local
       Helix logins with `mutagent providers mirror`. Or pick a model whose provider is configured.

    A coding agent should confirm with the user before adding a provider key. See
    [LLM providers and models](/helix/cloud/setup).
  </Accordion>

  <Accordion title="The launch is refused with HTTP 422 for the model">
    The `--model` value is not in the workspace's list. Copy an ID exactly from
    `mutagent helix models`, in the form `provider/model`.
  </Accordion>

  <Accordion title="My local models or local default are not listed">
    The cloud list comes from the workspace's active LLM providers, not from your machine. Mirroring
    copies API keys and custom model declarations, but not OAuth logins, keys stored as references,
    or your local default model. Read the mirror report for skipped entries, then check both lists:

    ```bash theme={null}
    mutagent providers list
    mutagent helix models
    ```

    Entries after "Not usable by Helix Cloud" are LLM providers whose keys Helix cannot load into a sandbox.
  </Accordion>

  <Accordion title="The model call fails after the run starts">
    The key or endpoint of the LLM provider is wrong or has no access to that model. Run
    `mutagent providers test <id>`, fix the LLM provider configuration, and run again. Do not put a
    model key into an Environment to work around it.

    In `--mode json`, a failed model call can still end with exit code 0. Look for an assistant
    message with `stopReason: "error"` and read its `errorMessage`.
  </Accordion>
</AccordionGroup>

## Launch arguments

<AccordionGroup>
  <Accordion title="mutagent helix with no task is refused">
    There is no terminal chat client for cloud sessions. Choose a mode: `-p "<task>"`,
    `--mode json "<task>"`, or `--mode rpc`. See [Run Helix in the cloud](/helix/cloud/overview#run-helix-in-the-cloud).
  </Accordion>

  <Accordion title="helix agent says the task is missing">
    The first positional argument of `helix agent` is the definition, not the task. Add the task with
    `-p`:

    ```bash theme={null}
    mutagent helix agent "You are a code reviewer." -p "Explain your review checklist."
    ```
  </Accordion>

  <Accordion title="My task is ignored in an interactive session">
    An interactive session ignores positional messages. Start with `--mode rpc` and no task, then write a prompt
    command to stdin:

    ```json theme={null}
    {"type":"prompt","id":"task-1","message":"Explain the evaluation steps."}
    ```
  </Accordion>

  <Accordion title="--rpc conflicts with --mode">
    `--rpc` means `--mode rpc`. Use one of them, not `--rpc` together with `--mode json`.
  </Accordion>

  <Accordion title="A flag that points at a local file is refused">
    The sandbox does not have your files. `--extension`, `--skill`, `--session`, `--continue`,
    `--resume`, and `@file` arguments are refused. `helix agent --file`, `--system-prompt`, and
    `--append-system-prompt` read the file on your machine and send its contents. To give the agent
    other files, put what it needs into the task.
  </Accordion>

  <Accordion title="--cwd is refused with --repository">
    With `--repository`, the checkout is the working directory. Leave out `--cwd`. A managed agent
    (`mutagent helix agent @<slug>`) refuses `--repository` too.
  </Accordion>

  <Accordion title="An agent name is not found">
    `--name` looks in your local agent directories, then in the agents built into the cloud image.
    Check the name, or pass the definition with `--file <path>`.
  </Accordion>

  <Accordion title="The sandbox provider name is refused">
    `--sandbox-provider` takes the name of a sandbox provider configured for the platform. The error
    lists the names you can use. Leave the flag out to use the default.
  </Accordion>
</AccordionGroup>

## Sessions

<AccordionGroup>
  <Accordion title="The stream disconnected">
    The session keeps running. Run the `session attach` command the CLI printed; its `--since` value
    starts after the last output you received. Reattaching never resends your input.
  </Accordion>

  <Accordion title="session send is refused with HTTP 409">
    One of these applies:

    * The session is `headless` in the `MODE` column. `-p` and `--mode json` runs cannot receive input.
    * The session has ended, or its input was closed.
    * The sandbox is being stopped for idling. Wait a few seconds and send again: once it has
      stopped, a send wakes it.

    Check the `STATUS` column of `mutagent helix session ls`.
  </Accordion>

  <Accordion title="My session shows stopped-for-idling, or send returns HTTP 404">
    `stopped-for-idling` means the sandbox had no activity for 15 minutes and was stopped; an
    interactive session was checkpointed first. Send it a message and it wakes, restored from that
    checkpoint, and gets the message:

    ```bash theme={null}
    mutagent helix session send hs1_… "carry on"
    ```

    HTTP 404 means the session can't be woken: it was headless, it ended, or its sandbox was removed.
    Start a new run. `mutagent helix session restore hs1_…` restores an interactive session by hand.
    See [Idle sandboxes](/helix/cloud/sessions#idle-sandboxes).
  </Accordion>

  <Accordion title="My reference stopped working after a restore">
    A restore starts a new session with a new reference. Find it in `mutagent helix session ls`, where
    it has status `restored`.
  </Accordion>

  <Accordion title="restore is refused with HTTP 409 MANAGED_AGENT_RESTORE_UNSUPPORTED">
    The session runs a managed agent, and a managed agent's session cannot be restored yet. Start a
    new run with `mutagent helix agent @<slug>`.
  </Accordion>

  <Accordion title="session checkpoint is refused with HTTP 409">
    The session has not finished a turn yet, so there is no transcript to save. Send a prompt, wait
    for the turn to end, and checkpoint again.
  </Accordion>

  <Accordion title="restore printed yellow lines">
    Each line names something that was not restored, such as workspace files that were never
    captured. The conversation is restored; the named parts are not. With `--on-drift refuse`, a
    restore whose transcript names missing files stops before switching.
  </Accordion>

  <Accordion title="Ctrl-C, abort, and signal do different things">
    * Ctrl-C on a launch sends SIGINT to Helix in the sandbox and waits for it to exit.
    * Ctrl-C on `session attach` only stops watching.
    * `session send <reference> --type abort` ends the current turn; the session keeps running.
    * `session signal <reference> --force` sends SIGINT, or SIGTERM with `--type SIGTERM`, even when
      Helix has stopped reading its input. Without `--force` it refuses and sends nothing.
  </Accordion>
</AccordionGroup>

## Environments

<AccordionGroup>
  <Accordion title="A variable is refused as an LLM provider key">
    The name matches a model key the workspace's LLM providers already supply. For model access, fix
    the [LLM provider](/helix/cloud/setup) instead. If you mean to override the key
    for runs that load this Environment, pass `--allow-provider-key` and store the value as a secret.
  </Accordion>

  <Accordion title="A variable name is reserved by the platform">
    Rename the entry. See [Which value is used](/helix/cloud/environments#which-value-is-used).
  </Accordion>

  <Accordion title="Environment not found">
    Check `mutagent env ls` and the selected workspace. Environments belong to one workspace.
  </Accordion>

  <Accordion title="Nothing to set">
    Pass at least one of `KEY=VALUE`, `--secret KEY=VALUE`, `--from-file <path>`, or
    `--secrets-from-file <path>`.
  </Accordion>

  <Accordion title="env rm, env unset or env set --replace refuses without --force">
    `mutagent env rm <name>` deletes the Environment and its secrets, `mutagent env unset <name> <KEY>`
    removes entries, and `env set --replace` removes every entry you did not name, so all three
    require `--force`. None of them asks for confirmation: without `--force` they exit 1 with
    `CONFIRMATION_REQUIRED` and change nothing.
  </Accordion>
</AccordionGroup>

## LLM provider mirroring

<AccordionGroup>
  <Accordion title="mirror exits with code 1 and writes nothing">
    Without a terminal, `mirror` cannot ask for confirmation, so it refuses and writes nothing. Exit
    code 1 is also used when at least one entry failed to copy; the report says which. Run
    `mutagent providers mirror --json` to see the plan, review it, then run it again with `--yes`.
  </Accordion>

  <Accordion title="mirror exits with code 3">
    You are not signed in, or no workspace is set. Run `mutagent login` and select a workspace.
  </Accordion>

  <Accordion title="An entry is skipped">
    OAuth and subscription logins, keys stored as references, and configurations with unsupported
    fields are not copied. The report gives the reason for each. Add those LLM providers with
    `mutagent providers add` instead. See [Mirror your local Helix setup](/helix/cloud/setup#mirror-your-local-helix-setup).
  </Accordion>
</AccordionGroup>


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