Table of Contents

Overview of the issue

When you hit an error while using Claude Code, digging into the cause from scratch every time is a hassle. What helps is a reverse-lookup approach: start from the "symptom" and narrow down the likely cause from there. Here, common symptoms are organized alongside their likely causes and fixes.

Symptom: "frozen, no response"

First, try the first-response steps described in the official troubleshooting docs. If things look unresponsive, cancel the current operation with Ctrl+C, or restart the terminal itself. If that doesn't help, try running the "/doctor" command — it automatically checks your install status, configuration, MCP server connections, and context usage, which helps narrow down the cause.

Frequency: medium Impact: high (work grinds to a complete halt)

Symptom: "response cuts off partway / context error"

If you see a message like "Autocompact is thrashing," it likely means the automatic context-compression process is failing repeatedly as the conversation has grown long. In this case, rather than loading a large file all at once, instruct it to read the file in smaller chunks, or run the "/compact" command to manually clean up the context.

Symptom: "won't install / won't start"

A lot of cases stumble at the environment-setup stage itself. A common cause is a Node.js version below 18. Upgrading Node.js is essential here. If you're using nvm, running the command to switch to the LTS version usually resolves it.

Symptom: "auth error / can't connect"

If the error stems from your API key, it's worth checking whether the key was copied correctly, whether the environment variable name matches what's expected, and whether you've mixed up the key between sandbox and production environments. This is especially easy to lose track of if you're switching between multiple environments during development.

Symptom: "output feels like it's gotten sloppier"

Even without a clear error message, you might feel like "the responses have gotten worse than before." In this case, it's possible the default thinking-budget value has been quietly turned down. Running "/effort high" within the session raises the thinking budget back to its maximum.

Symptom: "only errors out on Windows"

Using Claude Code on Windows can surface some Windows-specific symptoms. A "claude command not found" error is often caused by the install directory not being on the shell's search path — if you're using WSL, running commands like "which npm" and "which node" helps confirm whether what's actually executing is a Windows binary (path starting with /mnt/c/) or a Linux one (path starting with /usr/, etc.).

Also, if you're on an older version of WSL (WSL1), you may see an error like "cannot execute binary file: Exec format error" — the cleanest fix here is to convert the distribution to WSL2 from PowerShell. On top of that, trying to log in via the browser under WSL2 can run into its own quirk, where the redirect from the browser doesn't reach Claude Code's local server and the login never completes. Since the fix depends on whether you're running the Windows-native version or the WSL version, getting clear on which environment you're actually running in is the first step toward solving the problem.

Summary: 3 commands to try first

If Claude Code starts acting up, try these three commands first:

  1. "/doctor" — automatically diagnose installation, configuration, MCP servers, and context usage
  2. "/compact" — manually clean up bloated context
  3. "/effort high" — raise the thinking budget if output quality feels like it's dropped

Keeping a reverse-lookup mindset — from symptom to cause — should get you to a fix much faster than blindly reinstalling over and over.

Related Articles