If Claude Code looks frozen, check the spinner first. A retry countdown such as Retrying in Ns means Claude Code is retrying a transient failure, so check status.claude.com and wait. With no retry message, look locally: press Ctrl+C, run claude doctor, try claude --safe-mode, compact the context, or restart and resume with claude --resume.
If Claude Code looks frozen, first check whether it is waiting on the API or stuck locally. Look at the spinner: the error reference says Claude Code retries transient failures up to 10 times and shows a Retrying in Ns · attempt x/y countdown. If you see that, check status.claude.com and wait. If there is no retry message, press Ctrl+C, and if that fails, close the terminal and run claude --resume in the same directory to get the session back.
This guide restates what the troubleshooting page and error reference document, as read in November 2026. It is not a record of reproducing a freeze. Where Anthropic does not document a cause, the text says so. For a live view of provider incidents, see the Claude Code status hub.
How to tell an outage from a local problem
The error reference splits the two by where the failure happens. A 5xx response or a 529 "at capacity" message comes from the API side: the docs say a 5xx "is not caused by your prompt, settings, or account", and a 529 "doesn't count against your quota". A Waiting for API response banner that reappears on every attempt is, per the docs, a network issue to treat as such, and Request timed out lists a slow network or proxy as a possible cause.
- Open status.claude.com, or the status page the error message names if you reach Claude through another provider.
- Watch the spinner for a retry counter. A counter means Claude Code is retrying a transient failure itself.
- If no incident is posted and the error persists, the docs say to run
/feedbackinside Claude Code so Anthropic can investigate.
Which symptom points where?
| Symptom | Likely cause | What to do |
|---|---|---|
Spinner shows Retrying in Ns · attempt x/y | Transient failure being retried | Check the status page and wait |
Repeated 529 Overloaded errors | API at capacity (the docs note capacity is tracked per model) | Try again in a few minutes or switch with /model |
No response from API or Request timed out | Slow network, or a proxy holding responses | Resend; if a proxy holds responses, raise API_TIMEOUT_MS or CLAUDE_STREAM_FIRST_BYTE_TIMEOUT_MS |
| Terminal stops responding to keys | Local process stuck | Ctrl+C, then close the terminal and run claude --resume |
| Slow, or a critical memory warning | Large context or heap over 2.5GB | /compact, or restart and run claude --continue |
| Slow or thin search results on WSL | Project on the Windows filesystem under /mnt/c/ | Move the project to the Linux filesystem |
| Garbled text in an editor terminal | GPU renderer in the integrated terminal | Run /terminal-setup |
What does a provider slowdown look like?
The error reference says Claude Code retries transient failures up to 10 times with exponential backoff before showing an error, so a failing request can look like a long pause. The default request timeout is 10 minutes. Streaming requests also have a first-byte deadline: the docs' example message is API Error: No response from API (waited 3m, then 10m on the retry). For that message the docs advise resending, or raising API_TIMEOUT_MS or CLAUDE_STREAM_FIRST_BYTE_TIMEOUT_MS if a proxy holds responses. Both are documented environment variables; change them only if you see those messages.
CLAUDE_CODE_MAX_RETRIES sets the number of retry attempts and defaults to 10. Lowering it makes a script surface failures sooner, for example:
CLAUDE_CODE_MAX_RETRIES=2 claude -p "your prompt"
That is a scripting aid, not a fix for a hung interactive session.
How do I rule out local causes?
- Press Ctrl+C. If that does not cancel the operation, close the terminal. The conversation survives: run
claude --resumein the same directory. - Run
claude doctorfrom your shell. Per the CLI reference it prints read-only installation and settings diagnostics without starting a session, including install health and settings-file validation errors. Inside a session,/doctordoes a fuller check and can offer fixes. - Try
claude --safe-mode. It starts with all customizations off. The docs describe it as a way to check whether a plugin, MCP server or hook is the source, and the debug your configuration page explains how to find which one. - Shrink the context. Run
/compact. If it repliesNot enough messages to compact., the docs say the conversation has too few turns to summarize, which can happen with a full context when a single large paste filled it./clearstarts fresh if you no longer need the conversation. - Restart between big tasks. A critical memory warning appears when the heap passes 2.5GB. Restart and run
claude --continueto resume in a clean process.
What if memory stays high or compaction loops?
If memory stays high, the docs describe /heapdump, which writes a heap snapshot and a diagnostics file to ~/Desktop (to the home directory on Linux without a Desktop folder). The snapshot contains your full conversation and credentials, so never attach it to a public issue. Only the -diagnostics.json file is safe to share. For the error Autocompact is thrashing, the docs advise reading oversized files in smaller chunks, running /compact with a focus, or moving large-file work to a subagent.
Is it WSL or the terminal?
On WSL, the docs say disk read penalties across file systems may produce fewer matches than expected, and claude doctor still shows Search as OK. They recommend more specific searches or keeping the project on the Linux filesystem (/home/) rather than /mnt/c/. For garbled glyphs in the VS Code, Cursor or Devin Desktop terminal, the docs name the terminal's GPU renderer as the likely cause, and /terminal-setup sets terminal.integrated.gpuAcceleration to "off".
What have users reported?
These are user reports on GitHub, not documented behaviour: issue 26224 describes prompts stalling for 5 to 20 minutes or more, and issue 46987 describes repeated stream idle timeouts with partial responses. Both were still open when checked in November 2026, and neither thread records an official fix. If your symptom is an error about sign-in rather than a freeze, read what "Authentication service was unavailable" means.
More practical writing for people building with AI tools is on the Lead Source blog.
Fixed? Two optional things
Check Anthropic’s status and get an alert when an incident is resolved: Claude Code status and alerts, an independent resource by Lead Source.
Official source: status.claude.com.
Written by the team at Lead Source, where the day job is lead source tracking: working out which marketing actually brings customers.