# 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, run `claude auth login`, and confirm `claude auth status --json` reports a `claude.ai` login. Unset `ANTHROPIC_API_KEY` and other Claude backend overrides. 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.
## An edit has no LSP diagnostics
- Confirm `capabilities.lsp.enabled` is `true`.
- Confirm the language-server command is installed and on `PATH`.
- Remember that only supported files changed through `write` or `hash_edit` trigger injection.
- Run normal project checks when diagnostics are delayed, stale, or absent.
## 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).