# Troubleshooting
[Feature docs index](README.md) ยท [Repository README](../../README.md)
Paths below use `~/.magi-code` unless `MC_HOME` is set. Errors report the resolved paths.
## Build or launch problems
- `cargo: command not found`: install Rust from <https://rustup.rs/> and restart your shell.
- `magi-code: command not found`: run through Cargo, install with `cargo install --path . --locked`, or add `~/.cargo/bin` to `PATH`.
- Alias runs in the wrong project: use `--manifest-path /absolute/path/to/magi-code/Cargo.toml` in the alias and keep the trailing `--` before CLI flags.
- `rg: command not found`: no external search binary is required; `grep` and `ffgrep` use the native bounded engine.
## Auth and provider problems
- `missing auth for provider 'openai-codex'`: run `/login openai-codex`. See [Provider authentication](provider-authentication.md) for provider-keyed OAuth records.
- `missing ChatGPT account id`: add `accountId` to the `openai-codex` auth record or use an access token that carries the account id claim.
- `provider 'openai-codex' requires provider-keyed OAuth auth`: do not use `--api-key` or `MC_API_KEY` for Codex OAuth.
- `missing auth for provider 'openai'`: configure `openai` as a custom provider first, or select `openai-codex` after `/login openai-codex`.
- `401`/`403` from Codex backend: token may be expired, scoped incorrectly, or from a mismatched account. Re-run `/login openai-codex`; do not paste tokens into logs.
- Wrong provider selected: check CLI flags, environment variables, cwd `.magi-code/settings.json`, then global settings. See [Configuration](configuration.md).
- Retired `claude-code` selection: stale selections fail; use `anthropic/<model>` and an Anthropic API key from `ANTHROPIC_API_KEY` or provider-keyed `anthropic` API-key auth. No model/auth migration occurs, and Claude Code OAuth/subscription credentials are not reused.
## Session, context, and skill problems
- Resume fails: verify the session id exists under `~/.magi-code/sessions`.
- Broad session permissions on Unix: run `magi-code sessions repair-permissions --dry-run` to inspect eligibility, then run command interactively or with `--yes`. It resolves `MC_HOME`, repairs only validated existing legacy layout, never recurses or follows links, and fails closed on unsafe layouts; inspect those manually. Default confirmation requires TTYs.
- Broken skills: validate each `SKILL.md` is readable and located under a supported skill root.
- Unexpected instructions: check both `~/.magi-code/AGENTS.md` and `AGENTS.md` in the directory where you launched `magi-code`.
## Provider stream timeouts
- `provider stream idle timeout after 120s without bytes`: the transport received no bytes for 120 seconds.
- `provider stream no semantic progress before timeout`: chunks arrived but produced no text, reasoning, tool, usage, or completion events for 60 seconds.
Either can appear as an incomplete partial response after progress. Check provider/network health before retrying. Failed or cancelled partial assistant text remains in session history.
For hook failures, use the [hook troubleshooting table](tool-call-hooks.md#troubleshooting-hooks). Never include tokens or raw auth output in bug reports.