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)

---

Other common failures

[placeholder for future sections: context-window errors, tool-use failures, session corruption, auto-compaction loops]