claw-code/TROUBLESHOOTING.md

Troubleshooting

Upstream stream-init failures (500 empty_stream)

Symptom: claw-code exits with 500 empty_stream: upstream stream closed before first payload or similar upstream stream-init error.

Root cause: Upstream provider (Anthropic, OpenAI, other) closed the HTTP connection before sending the first response payload. Common causes:

• Transient network issue between claw-code and provider
• Provider overload / temporary service degradation
• Authentication token expired or invalid
• Rate limit exceeded (even if not visible in response headers)

Mitigation:

1. Check credentials: Verify claw whoami shows the expected provider and account. Re-authenticate if expired.
2. Wait and retry: Provider transient issues usually resolve within 30-60 seconds. Wait a minute, then retry the same command.
3. Check provider status: Visit the provider's status page (e.g., status.anthropic.com, status.openai.com).
4. Reduce request size: If the prompt is large, try a smaller request first to isolate stream-init from context-window failures.
5. Check network: Ensure your network connection is stable. If behind a proxy, verify proxy allows streaming responses.

When to escalate:

• If stream-init failures persist >10 minutes across multiple requests
• If claw whoami fails to authenticate
• If no provider status page shows degradation

Related pinpoint: #290 (typed stream-init failure envelope — future improvement for better diagnostics)

---

Context-window-blocked errors

Symptom: claw-code exits with context_window_blocked or similar provider error when resuming a long session, or when sending a request with a very large prompt + accumulated history.

Root cause: Session size exceeded provider context window before claw-code's auto-compaction could reduce it. Auto-compaction is currently REACTIVE-AFTER-SUCCESS — it only fires after a successful provider response. If the request itself is oversized, compaction never runs.

Mitigation:

1. Resume with manual compact: claw resume <session> --compact-before (if available); else manually compact via /compact slash command before retrying
2. Start a fresh session: Sometimes the cleanest path; existing session-state preserved in ~/.claw/sessions/<id>/
3. Reduce prompt size: If interactive, send shorter prompts; truncate file contents before pasting
4. Adjust threshold: Lower CLAW_AUTO_COMPACT_INPUT_TOKENS_THRESHOLD env var (default varies by provider)

Related pinpoints: #287 (auto-compaction reactive-not-preflight, CRITICAL), #283 (threshold env-only no settings.json key), #288 (failure envelope omits diagnostics)

---

Manual /compact reports "session below compaction threshold"

Symptom: You run /compact to manually compact a session, but it reports session below compaction threshold even though the session feels large.

Root cause: The "below threshold" message is currently a catch-all for multiple skip reasons:

• Too few compactable messages
• Already compacted (only summary remains)
• Compactable tokens below threshold
• Tool-use/tool-result boundary preserved
• Live vs resume threshold divergence

Mitigation:

1. Check session state: claw session info <id> to inspect message count, total tokens
2. Force compaction: Currently no --force flag exists; track #289 for typed skip-reason discriminants
3. Workaround: Continue session and let auto-compact fire after next provider response (when reactive-after-success path is available)

Related pinpoint: #289 (manual /compact skip-reason flattened, lacks typed discriminants)

---

Parallel agent stuck in "running" state

Symptom: A parallel agent lane shows status: running indefinitely, never transitioning to completed or error. Downstream coordination treats it as still-working.

Root cause: Agent::execute_agent writes a running manifest BEFORE spawning a detached std::thread::spawn. The JoinHandle is dropped. If the process crashes during agent execution, the manifest stays as running forever (zombie state). No heartbeat or stale-reaper exists.

Mitigation:

1. Manual cleanup: Inspect ~/.claw/agents/<lane>/ and remove stale manifest.json files where last-modified > N minutes ago
2. Restart agent lane: claw agent restart <lane>
3. Kill orphaned processes: pgrep claw to find lingering processes

Related pinpoint: #286 (Parallel Agent detached-thread no-heartbeat no-reaper)

---

Sustained upstream provider failures (500 empty_stream repeating)

Symptom: Same upstream provider error (e.g., 500 empty_stream: upstream stream closed before first payload) repeats 5+ times in <60 minutes. Retries hit the same dead upstream blindly.

Root cause: claw-code does NOT detect repeat-failure patterns. No circuit-breaker. No automatic provider-fallback when configured. Each retry attempts the same provider+endpoint regardless of recent failure history.

Mitigation:

1. Manual circuit-breaker: Wait 5-10 minutes after repeated failures before retrying
2. Switch provider: If you have multiple providers configured (ANTHROPIC_API_KEY + OPENAI_API_KEY), restart with different model prefix (e.g., gpt-4 instead of claude-)
3. Check provider status pages: status.anthropic.com, status.openai.com
4. Verify upstream endpoint: If using a proxy (CCAPI, custom OpenAI-compatible endpoint), check proxy logs

Related pinpoints: #291 (no repeat-failure detection / circuit-breaker), #285 (declarative providers config for fallback), #290 (stream-init failure envelope)

---

Other common failures

[placeholder for future sections: tool-use failures, session corruption]