Troubleshooting
Feature docs index · Repository README
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 withcargo install --path . --locked, or add~/.cargo/bintoPATH.- Alias runs in the wrong project: use
--manifest-path /absolute/path/to/magi-code/Cargo.tomlin 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 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-keyorMC_API_KEYfor Codex OAuth.missing auth for provider 'openai': setOPENAI_API_KEYbefore launch, or choose another configured provider through/login.401/403from 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.
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-runto inspect eligible repairs, then run the command interactively or with--yes. It resolvesMC_HOME, never recurses or follows links, and fails closed on unsafe layouts. Default confirmation requires TTYs. - Broken skills: check that each
SKILL.mdis readable and located under a supported skill root. - Unexpected instructions: check both
~/.magi-code/AGENTS.mdandAGENTS.mdin the directory where you launchedmagi-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. Never include tokens or raw auth output in bug reports.