How to Troubleshoot Claude Code When It Hangs or Stops Responding to Requests

When Claude Code stops responding, the spinner alone does not show what has failed. Claude’s service may be slow, the local command-line interface (CLI) may be stuck, or a panel in an integrated development environment (IDE) or Desktop may have lost contact with the CLI. Each problem needs different checks. If you restart right away, you may lose useful session details without finding the cause.

First check what still works. Check whether the terminal accepts input and whether Claude Code is using CPU. Then open a new CLI session outside Desktop or an IDE to see whether the problem occurs there. After those checks, check Claude’s service status. Review your local settings and network connection before deciding whether to interrupt or restart Claude Code.

Check what has stopped responding

While Claude Code is paused, note how long the pause lasts and whether the terminal responds to ordinary controls. Check CPU use in your operating system’s process monitor. High CPU use suggests the CLI is busy or stuck repeating local work. Low CPU use does not prove that the service connection has stalled, but it shows that the local CLI is not using much processing power.

Individual reports show why the spinner alone cannot identify the problem. One describes an unresponsive macOS CLI using one CPU core at 100%. Another describes a long pause while the session appeared to wait for response data arriving in pieces. These reports describe specific setups; they do not confirm the cause of other users’ problems. (High-CPU CLI report, long response-pause report)

Check the Claude status page for incidents affecting Claude Code or the Claude API. The page reports incidents during specific time windows. An incident during your pause may explain it, but a clear status page does not show that your local CLI, account, or network connection is working properly.

Test the CLI separately from Desktop or an IDE

If you use Claude Code inside an IDE or Desktop, open a new terminal and try a small prompt that has little effect on your project. If Claude Code responds there but the panel remains stuck, investigate the panel or its connection to the CLI instead of reinstalling the command-line tool.

A report about VS Code on Windows describes a case where the terminal worked but the extension’s display stopped responding. A separate report about Remote-SSH suspects a problem with how the extension communicates with the CLI and mentions leftover CLI processes. These reports describe possible problems with particular interfaces, and their observations do not establish fixes that work for everyone. (VS Code report, Remote-SSH report)

If both a standalone CLI session and a session inside Desktop or an IDE fail, check Claude’s service and your local settings. If only a remote or embedded session fails, note that difference. It gives anyone investigating the problem a useful starting point.

Check installation, settings, and network access

Run claude doctor to check your installation and settings. Anthropic describes it as a diagnostic command that reads settings and reports warnings with suggested fixes. It is a useful first check, but it does not detect every cause of a hang. The Claude Code setup documentation explains the command.

On a managed network, check that your proxy (a server that forwards network traffic), firewall, or custom certificate settings let Claude Code reach the services required for your sign-in and provider setup. A working browser connection does not confirm that the CLI can reach those services. Anthropic’s network configuration documentation lists the requirements and explains proxy and certificate settings. Follow the guidance for your network instead of copying an allowlist, a list of permitted network addresses, from another environment.

Capture details before changing anything

If the problem happens again and it is safe to reproduce, start Claude Code with --debug or --debug-file <path>. The CLI reference also documents --verbose, which provides more detailed output. Check the logs before sharing them because they may contain sensitive project or session information. See the CLI reference for the supported options.

Record which Claude Code version you use and how you installed it. Note your operating system and terminal or interface, and whether you use a proxy, VPN, remote connection, or third-party provider. Also record when the pause happened, which model you selected, any visible error text, CPU activity, and whether a new CLI session works. These details help distinguish a service delay from a local problem or an interface-specific failure.

Recover without losing more context

If the session still responds to controls, use its normal stop or interrupt control before closing it. Do not send more prompts while the original request may still be running, especially if Claude Code could edit files or run commands. A follow-up prompt has resumed some reported pauses, though users have also reported failures, so it is not a dependable way to diagnose or recover from a pause.

If Claude Code remains unresponsive, you may need to restart it. A forced quit can discard session details that you have not saved, so preserve the transcript and diagnostic information first if possible. Do not kill processes by name or apply a workaround from an individual report unless you have confirmed that it fits your setup. Take particular care when you use remote or multi-session environments.

What I'm building

Delegate tasks. Get software.

Give Vroni a GitHub issue, bug report, spec, or rough idea. It reads the repo, plans the change, writes code, runs checks, and works toward a review-ready pull request.

Take a look at vroni.com