Browse documentation

Technical documentation / Reference

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

Auth and provider problems

Session, context, and skill problems

Provider stream timeouts

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.

Edit this page on GitHub ↗