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

# Troubleshooting

> Common errors and how to fix them

## Authentication

**`please login: run \`mulerun login\`\`**

The cached OAuth token is missing or expired. Re-run `mulerun login`, or
for non-interactive setups export `MULERUN_TOKEN`.

**Login opens a browser but never completes.**

Check that your browser can reach `https://mulerun.com`. Behind a
corporate proxy, set `MULERUN_PROXY` before running `mulerun login`.

**Token works for some commands but not others.**

Run `mulerun internal-auth token-info` to see the cached token's expiry
and scopes. Run `mulerun internal-auth check` to round-trip it against the
server.

## Network and proxy

**Timeouts on every command.**

Set `MULERUN_PROXY` to your egress proxy. Use `socks5h://` (not `socks5://`)
to keep DNS on the proxy side — required when your local resolver cannot
reach MuleRun hostnames.

**TLS verification failure on a corporate network.**

For development only, pass `--insecure`. For production environments,
import your corporate CA into the system trust store; the CLI uses the OS
trust store directly.

## `code` and `studio`

**First `mulerun code` / `mulerun studio` is slow.**

The first invocation installs the runtime under `~/.mulerun/vendor/`.
Expect 10-30 seconds on a fast link. Subsequent calls reuse the vendored
copy.

**Runtime is wedged after a failed install.**

```bash theme={null}
mulerun code reset       # remove the agent runtime
mulerun studio reset     # remove the studio engine
```

The next invocation reinstalls cleanly.

**Wrong model is being used.**

`mulerun code -m <model>` and `mulerun studio run ... --model <model>`
pin a specific id. Use `mulerun code models -a <agent>` and
`mulerun studio params <endpoint>` to see the allow-list.

## Upgrades

**`mulerun upgrade` fails with a registry error.**

Confirm `MULERUN_NPM_REGISTRY` (if set) is reachable. External registries
not on the built-in allow-list require
`MULERUN_ALLOW_EXTERNAL_NPM_REGISTRY=1`.

**Want to freeze the CLI at a specific version.**

Set `MULERUN_NO_AUTO_UPGRADE=1`. Auto-upgrade in the background is then
disabled; `mulerun upgrade` invoked manually still works.

## Diagnostics

When in doubt, run:

```bash theme={null}
mulerun doctor
```

This is what we'll ask for if you open a support ticket.

## Exit codes

| Code | Meaning                                                    |
| ---- | ---------------------------------------------------------- |
| `0`  | Success                                                    |
| `1`  | General error (validation, network, terminal task failure) |
| `2`  | Build / profile mismatch (the binary will refuse to run)   |

When scripting against the CLI, always check `$?` before parsing the JSON
output — a failed call may still emit JSON, but the shape will contain an
error field rather than results.