# Troubleshooting
[Feature docs index](README.md) · [Repository README](../../README.md)
## Purpose
Diagnose common launch, authentication, provider, session, context, and skill problems.
## Details
### 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`: install ripgrep for faster `ffgrep`; fallback search still works without it.
### Auth and provider problems
- `missing auth for provider 'openai-codex'`: run `/login openai-codex` or add provider-keyed OAuth credentials under `~/.magi-code/auth.json`.
- `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.
- Claude Code `429 rate_limit_error` on `sonnet`, `opus`, or `fable`: usually billing route marker missing from OAuth `system` text, not actual rate limiting. Check `src/providers/claude_code/body.rs` for `CLAUDE_CODE_BILLING_HEADER` injection only when `ClaudeCodeAccessMode::is_oauth()` is true. API-key fallback must not include it.
- Claude Code `404 not_found_error`: invalid or stale model id. Check `resolve_claude_code_model_alias()` in `src/model_catalog.rs`; current aliases map `sonnet` to `claude-sonnet-4-6`, `opus` to `claude-opus-4-8`, and `fable` to `claude-fable-5`.
- Diagnose Claude Code premium-model failures: run a minimal prompt with no tools, verify model ids through Anthropic `/v1/models`, then inspect the serialized request body. OAuth premium-model requests need `x-anthropic-billing-header: cc_version=2.1.185; cc_entrypoint=sdk-cli; cch=00000;` at the start of `system` text and messages URL `https://api.anthropic.com/v1/messages?beta=true`.
- Wrong provider selected: check `--provider`, `MC_PROVIDER`, and `~/.magi-code/settings.json` in precedence order.
### 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`.
---
[Back to feature docs](README.md) · [Back to repository README](../../README.md)