# 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.
## 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`: repeat `/login openai-codex`. Do not edit or paste access tokens to repair login.
- `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'`: set `OPENAI_API_KEY` before launch, or choose another configured provider through `/login`.
- `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).
## 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 eligible repairs, then run the command interactively or with `--yes`. It resolves `MC_HOME`, never recurses or follows links, and fails closed on unsafe layouts. Default confirmation requires TTYs.
- Broken skills: check that 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.
### Automatic retries before progress
API provider requests retry only before text, reasoning, tool, usage or completion progress. HTTP `429` and `529`, and Anthropic stream `rate_limit_error` and `overloaded_error`, allow four total attempts with waits of 2, 10 and 20 seconds. HTTP `408`, `425`, `500`, `502`, `503`, `504`, Anthropic stream `api_error`, and retryable transport/completion failures allow three total attempts with waits of approximately 250 and 750 milliseconds (±20% jitter). Other Anthropic stream error types are not retried.
On non-success HTTP responses, `retry-after-ms` (integer milliseconds) takes precedence over `retry-after` (integer seconds or HTTP-date). A valid server wait replaces that attempt's scheduled wait without adding attempts. Malformed, negative, overflowing or overlong header values are ignored; a past date means zero wait. A wait above 60 seconds fails immediately with `provider asked to retry after …s; exceeds 60s automatic retry limit`, rather than retrying early. Every wait remains cancellable with Esc (25-millisecond cancellation polling).
After progress, failures remain incomplete responses and accepted partial text is retained, never replayed through this retry loop. Anthropic `message_start` with usage already counts as progress, even before text. This also holds when progress and an error arrive in one network chunk. Exhausted retries report `provider request failed after N attempts`. OpenAI, Codex, custom compatible endpoints and Anthropic API share this policy; Claude Subscription admission is separate and unchanged. Retries never switch provider, model or billing path.
The agent's separate, single incomplete-response continuation remains unchanged: when safe, it can request a continuation that includes accepted partial text instead of replaying the original request. That is not a transport retry.
### Repeated whitespace in tool arguments
`provider tool call arguments degenerated into whitespace` means a tool call exceeded 4 KiB of consecutive JSON whitespace outside string values. Responses, Chat Completions and Anthropic argument streams stop immediately at this limit. Whitespace inside strings and normal JSON indentation remain valid. Outside-string whitespace alone does not reset the 60-second semantic-progress timeout; the byte-idle timeout and 1 MiB argument limit remain unchanged.
If no complete tool call or function response item was observed, the agent can use its existing single automatic continuation to ask: “Your previous tool call arguments degenerated into repeated whitespace and were discarded. Re-issue the call with compact JSON arguments.” This prompt is ephemeral, not a saved user message. Session `diagnostic` and `abort_recovery` events record the tool name, argument byte count and whitespace run length without raw arguments. The automatic-continuation budget is unchanged; a repeated failure requires manual continuation. Gemma's inline text tool syntax is not a streamed JSON argument accumulator and does not use this detector.
For hook failures, use the [hook troubleshooting table](tool-call-hooks.md#troubleshooting-hooks). Never include tokens or raw auth output in bug reports.