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 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 uses the native bounded engine.

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: 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.

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.

For hook failures, use the hook troubleshooting table. Never include tokens or raw auth output in bug reports.

Edit this page on GitHub ↗