← Blog · 2026-10-24

Claude Code Stuck or Not Responding? 12 Causes and Fixes

30-second test: press Esc. It stops the current response or tool call mid-turn and Claude keeps the work done so far, so you can redirect it. Then read what was on screen. A dialog asking you to approve something means Claude was waiting on you: start at cause 1. A command or MCP tool still running: cause 3. Retrying in Ns · attempt x/y or Waiting for API response: cause 8. If the keyboard does nothing at all, go to cause 12.

"Stuck" in Claude Code is usually one of four things, and only the last one is a real freeze:

• It's waiting on you. A permission prompt or a question is open, and those don't close on their own.
• A tool is still running. A Bash command, an MCP tool call, a hook or a subagent hasn't returned yet.
• It's waiting on the API. Claude Code is retrying a failed request or waiting for a response that isn't arriving.
• The session itself is struggling. A huge context, high memory use or a terminal that renders badly.

Two keys cover most of it. Esc interrupts Claude, and if you had messages queued, Claude Code sends them next. Ctrl+C interrupts a running operation too; if nothing is running, the first press clears your prompt and a second press exits. Exiting doesn't lose the conversation: run claude --resume in the same folder to pick it back up.

Waiting on you: 2 causes

1. A permission prompt is waiting for an answer. Permission prompts, including plan approval, never resolve on idle. If you switched to another window, Claude Code may have been waiting the whole time. To stop missing them, get a notification: by default Claude Code sends a desktop notification only in Ghostty, Kitty and iTerm2. In other terminals, add "preferredNotifChannel": "terminal_bell" to your settings to ring the terminal bell, or add a Notification hook. The hook's permission_prompt type fires once a prompt has waited about six seconds with no typing, and it works in terminals that get no desktop notification, such as Warp or the VS Code integrated terminal. Inside tmux, notifications don't reach the outer terminal until you turn on allow-passthrough in ~/.tmux.conf. If the real problem is that it asks too often, our guide to Claude Code asking for permission shows how to pre-approve safe commands.
2. Claude asked you a question and is waiting. When Claude needs a decision it shows a multiple-choice question, and it stays open until you answer. If you'd rather it carry on when you're away, set askUserQuestionTimeout to 60s, 5m or 10m in your user settings.json, or from the Question auto-continue timeout row in /config. When the time runs out, the dialog submits any options you'd selected and tells Claude you may be away, so it proceeds on its own judgment. The timer doesn't count down while your terminal window is focused, and it never starts in a background session or while Remote Control is connected. It only applies to these questions, never to permission prompts.

A tool is still running: 5 causes

3. A long Bash command is running in the foreground. A foreground Bash command gets a 2-minute timeout by default, and Claude can ask for up to 10 minutes on a single command. When a command reaches its timeout without finishing, Claude Code moves it to the background instead of killing it (unless the command starts with sleep), and the result says Command did not complete within its 120s timeout and was moved to the background. So a 10-minute test suite can look like a frozen session for up to 10 minutes. Don't wait: press Ctrl+B to move the running command to the background now (tmux users press it twice, because Ctrl+B is tmux's prefix key), and use /tasks to see and stop background work. To change the limits, set BASH_DEFAULT_TIMEOUT_MS (default 120000) and BASH_MAX_TIMEOUT_MS (default 600000) in your shell or the env block of your settings.
4. A process that never exits, or a busy subagent. A dev server or a watch build doesn't finish by design, so running one in the foreground holds the turn until its timeout. Ask Claude to run it in the background: it then gets a task ID and Claude keeps working while it runs. Subagents can hold a turn the same way. /tasks lists running shells and subagents, and Ctrl+X Ctrl+K (pressed twice within 3 seconds) stops every background subagent in the session. Subagents have their own stall timeout, CLAUDE_ASYNC_AGENT_STALL_TIMEOUT_MS, which defaults to 10 minutes.
5. An MCP tool call is hanging. By default an MCP tool call can run for a very long time: MCP_TOOL_TIMEOUT defaults to 100000000 ms, about 28 hours. Two other timers usually end a dead call sooner. An HTTP, SSE or claude.ai connector server times out each request after 60 seconds by default. And an idle timeout aborts a call when the server sends no response and no progress for 5 minutes on network servers or 30 minutes on local stdio servers; you can change it with CLAUDE_CODE_MCP_TOOL_IDLE_TIMEOUT (Claude Code v2.1.187 or later). To cap one slow server, add a timeout field in milliseconds to its .mcp.json entry, for example "timeout": 600000 for ten minutes. In the moment, press Esc, then open /mcp and select Reconnect for that server.
6. An MCP server is slow to start. Each server gets 30 seconds to start by default, and a slow server can run past that. Set a different startup timeout with MCP_TIMEOUT, for example MCP_TIMEOUT=10000 claude for 10 seconds. If you see MCP server "<name>" connection timed out. Your computer went to sleep or its clock changed while connecting., reconnect from /mcp and keep the computer awake until it finishes. Servers that fail outright, show zero tools or never appear are covered in Claude Code MCP server not connecting.
7. A hook is blocking. Unless a hook runs with async: true, Claude Code waits for it to finish before it carries on. A command hook can run for 600 seconds by default before it's cancelled. UserPromptSubmit hooks run before every prompt and block until they finish, so a stuck one stalls the whole session; their default timeout is 30 seconds. Run /hooks to see which hooks are active, and set a shorter timeout (in seconds) on a slow hook's entry. To confirm a hook is the cause, start with claude --safe-mode, which loads no hooks, MCP servers, plugins or CLAUDE.md, or start with claude --debug and read which hooks ran and what they returned. Claude Code hooks not working covers the rest.

Waiting on the API: 3 causes

8. Claude Code is retrying a failed request. Claude Code retries transient failures up to 10 times with exponential backoff, and the spinner shows Retrying in Ns · attempt x/y while it does. During a 529 overload it also names where to check service status, such as status.claude.com. That can look like a hang, but it's working as designed. Check status.claude.com, or switch models with /model, since capacity is tracked per model. In scripts, set CLAUDE_CODE_MAX_RETRIES lower to surface failures faster. What each error means once retries run out is in Claude Code API errors.
9. The response isn't arriving. If no data arrives on the response stream for 20 seconds, the spinner shows Waiting for API response · will retry in … · check your network. The request hasn't failed yet, and the banner clears on its own once data resumes. If it shows on every attempt, test the network from the same shell with curl -I https://api.anthropic.com. If curl works but Claude Code doesn't, run echo $ANTHROPIC_BASE_URL: a leftover value that points at a local proxy or gateway that's no longer running sends every request to the wrong place. Requests that never answer end in Request timed out (the default request timeout is 10 minutes, set by API_TIMEOUT_MS) or API Error: No response from API. If a proxy or gateway on your network holds responses until they complete, raise API_TIMEOUT_MS or CLAUDE_STREAM_FIRST_BYTE_TIMEOUT_MS so Claude Code waits longer.
10. A corporate proxy or TLS inspection is in the way. If your network needs a proxy, set HTTPS_PROXY before you launch Claude Code. If the proxy inspects TLS with its own certificate, Claude Code doesn't trust it, and you'll see SSL certificate verification failed or Self-signed certificate detected. Point Claude Code at your organization's CA bundle with NODE_EXTRA_CA_CERTS=/path/to/ca-bundle.pem. Don't set NODE_TLS_REJECT_UNAUTHORIZED=0, which turns off certificate checks entirely. Version matters here: as of v2.1.199 a certificate failure isn't retried, so the error shows up on the first attempt. Earlier versions spent a few minutes retrying first, which looked exactly like a hang. Run claude --version and update with claude update if you're behind.

The session itself: 2 causes

11. A huge context or a compaction loop. On large codebases Claude Code can use a lot of CPU and memory. If you see Autocompact is thrashing: the context refilled to the limit..., compaction worked but a file or tool output refilled the window several times in a row, so Claude Code stopped retrying. Ask Claude to read the big file in smaller chunks, run /compact with a focus such as /compact keep only the plan and the diff, hand the large-file work to a subagent, or /clear if you don't need the earlier conversation. /context shows what's filling the window. If a session's memory passes 2.5GB, you'll get a critical memory warning: restart Claude Code and run claude --continue to resume the conversation in a fresh process. Our guide to Claude Code context filling up fast has more ways to keep sessions small.
12. The terminal or IDE is the problem. If keys do nothing, press Ctrl+C to try to cancel. If it's still unresponsive, close the terminal and restart; claude --resume in the same folder brings the conversation back. If text renders as boxes, smears or the wrong characters in the VS Code, Cursor or Devin Desktop integrated terminal, the terminal's GPU renderer is the likely cause: run /terminal-setup to set terminal.integrated.gpuAcceleration to "off", then reload the window. If you're using fullscreen rendering and something looks wrong, /tui default switches back to the classic renderer with your conversation intact. One version note: before v2.1.208, resuming a session that held a very large Markdown table could stall while it re-rendered every row; newer versions show the first 200 rows.

Still stuck?

Run /doctor inside Claude Code for an automated check of your installation, settings, extensions and context usage, or claude doctor from your shell if claude won't start (that case has its own guide: Claude Code command not found). To see what Claude Code was doing when it stalled, start with claude --debug, or claude --debug=mcp to focus on MCP servers, reproduce the problem, and read the log at ~/.claude/debug/<session-id>.txt. Inside a running session, /debug turns logging on from that point and asks Claude to read the log for you. claude --safe-mode starts with every customization off; if the hang goes away there, one of your customizations, such as a plugin, MCP server or hook, is the cause. Report anything that still looks like a bug with /feedback.

Facts on this page come from Anthropic's Claude Code docs on troubleshooting, errors, interactive mode, the tools reference, MCP, hooks, environment variables, network configuration, terminal configuration, the settings reference, commands, debugging your configuration and the CLI reference. This guide isn't affiliated with Anthropic.

Missed permission prompts are the most common "stuck" session. Our Claude Code Power Config Pack includes a tested hook that notifies you when Claude needs input, plus permission presets so it asks less often, $6 with the launch code while it lasts.