# Troubleshooting
Paths below use `~/.magi-code` unless `MC_HOME` is set. Error messages show resolved paths.
## Magi-code does not start
**`cargo: command not found`**
Install Rust from [rustup.rs](https://rustup.rs/) and restart your shell.
**`magi-code: command not found`**
Add Cargo's binary directory to `PATH`:
```sh
export PATH="$HOME/.cargo/bin:$PATH"
```
If you installed from source, run `cargo install --path . --locked` from the repository.
## Provider login fails
**`missing auth for provider 'openai-codex'`**
Run `/login openai-codex` and complete browser sign-in.
**A Codex request returns `401` or `403`**
Your token may be expired, scoped incorrectly, or associated with another account. Run `/login openai-codex` again. Do not paste token contents into an issue or log.
**OpenAI API does not appear**
Set `OPENAI_API_KEY`, choose OpenAI in `/login`, save its prefilled custom-provider configuration, refresh the model catalog, then select an `openai/<model>`.
**Anthropic does not authenticate**
Set `ANTHROPIC_API_KEY` in the environment that launches magi-code. The `anthropic` provider uses API keys only. For claude.ai subscription access, select the separate `claude-subscription` provider instead.
**Claude Subscription is unavailable**
Install Claude Code and run `claude auth login` for claude.ai access, then refresh the catalog in `/settings` → **Models**. Magi-code removes API-key and alternate-backend overrides from its Claude child processes; you can keep `ANTHROPIC_API_KEY` set for Anthropic API models. Magi-code looks for `claude` on `PATH`, then `~/.local/bin/claude`. Native Windows is unsupported; run magi-code and Claude Code inside WSL.
**Wrong provider or model is selected**
Check launch flags first, then project settings in the exact launch directory, then global settings. Open `/settings` → **Models** to refresh the catalog.
## A session does not resume
Use `/sessions` to confirm the session exists. For `--resume`, copy its exact ID.
On Unix, broad permissions can block access. Inspect eligible repairs:
```sh
magi-code sessions repair-permissions --dry-run
```
Then run `magi-code sessions repair-permissions` if the proposed changes are correct.
## Instructions or skills are missing
- Launch from the directory containing the intended `AGENTS.md`.
- Confirm a skill uses `<skill-name>/SKILL.md` under a supported root.
- Open `/skills` and check whether the skill is disabled.
- Save settings with `Ctrl-S`. Skills and other affected runtime state refresh for future actions.
For unexpected instructions, check both `~/.magi-code/AGENTS.md` and the launch directory's `AGENTS.md`.
## A response times out
`provider stream idle timeout after 120s without bytes` means no bytes arrived for 120 seconds.
`provider stream no semantic progress before timeout` means bytes arrived but produced no usable response or tool progress for 60 seconds.
Check provider and network health before retrying. Partial assistant text may remain in session history after a failure or cancellation.
## A provider is overloaded or rate-limited
Before any text, reasoning, tool, usage or completion progress, HTTP `429`/`529` and Anthropic stream `rate_limit_error`/`overloaded_error` retry up to four total attempts, waiting 2, 10 and 20 seconds. HTTP `408`, `425`, `500`, `502`, `503`, `504`, stream `api_error` and retryable transport/completion failures allow three total attempts with roughly 250/750-millisecond waits (±20%). Other stream error types are not retried.
Server `retry-after-ms` (milliseconds) or `retry-after` (seconds or HTTP-date) replaces each scheduled wait; milliseconds take precedence. Invalid values use the schedule. Waits above 60 seconds fail immediately with an automatic-retry-limit message: retry manually later. Esc cancels waits; polling occurs every 25 milliseconds. Exhaustion reports `provider request failed after N attempts`.
Once progress arrives, this loop does not retry and partial text is kept. Anthropic message-start usage counts as progress. This policy covers API providers, including OpenAI-compatible endpoints and Codex, not Claude Subscription admission. No retry changes model, provider or billing path.
## An MCP server is unavailable
```sh
magi-code mcp list
magi-code mcp test <server>
```
Confirm the definition is in global or exact-directory `.mcp.json`, approve it with `/mcp`, and restart. Definitions cannot approve themselves.
## Need exact error behavior?
See the [technical troubleshooting reference](../features/troubleshooting.md) and feature-specific references linked from the [user guide](README.md).