Blog
4 min read

Claude Code Not Working? Fixes for the Most Common Problems

"command not found: claude", login loops, API errors, rate limits, slow or stuck sessions, permission prompts that never stop, and Claude ignoring your instructions. A troubleshooting guide for the problems people hit most, starting with claude doctor.

Claude Code usually just works. When it doesn't, the problem is almost always one of a handful of things. Start with the built-in health check, then find your symptom below.

Step zero: claude doctor

claude doctor

It checks your installation, version, settings files and update status, and flags conflicts (like two installs fighting). Inside a session, /doctor does the same. Also run claude --version — if you're several versions behind, claude update may fix things on its own.

"command not found: claude"

The install worked but your terminal can't find the program.

  1. Open a new terminal window. The current one doesn't know about the new install yet.
  2. Check your PATH. The native installer puts claude in ~/.local/bin. If that folder isn't on your PATH, add it (the installer prints the line to add). (The PATH variable and "command not found")
  3. On Windows, make sure you're in the same environment you installed in — a WSL install isn't visible from PowerShell, and vice versa. (Claude Code on Windows)

Two versions, or an old version keeps running

If you installed with npm and the native installer (or Homebrew), the older one may run first. claude doctor reports this. Uninstall the one you don't want — for example npm uninstall -g @anthropic-ai/claude-code. (How to install Claude Code)

Login problems

  • Browser doesn't open (common over SSH or on servers): copy the URL Claude Code prints, open it on any device, and paste the code back.
  • "Not available on your plan": the free Claude plan doesn't include Claude Code. Check you're signed into a Pro, Max, Team or Enterprise account, or using an API key. /status shows the active account.
  • Wrong account or stuck session: run /logout, then claude again to sign in fresh.
  • An ANTHROPIC_API_KEY in your environment makes Claude Code use API billing instead of your subscription. Unset it if that's not what you want. (Claude Pro vs Max vs API)

Network and API errors

  • Corporate networks: proxies and TLS inspection cause certificate errors and 403s. Set HTTPS_PROXY and point NODE_EXTRA_CA_CERTS at your company's certificate bundle; Anthropic's network docs cover the details.
  • "Overloaded" or 5xx errors: usually temporary. Check status.claude.com and retry.
  • Timeouts on very long tasks: break the task into smaller steps.

You hit a usage limit

Subscriptions have usage limits that reset over time. /usage shows where you stand. To make limits last longer: switch to a smaller model for routine work, clear context between unrelated tasks, and avoid making Claude read huge files it doesn't need. (Claude Code usage limits, keeping costs down)

It's slow, or seems stuck

  • A long-running command (a dev server, a watcher) is blocking. Press Esc, then ask Claude to run it in the background, or use Ctrl+B.
  • A bloated context. Long sessions get slower and less sharp. Use /compact, or /clear when you switch tasks. (/compact vs /clear)
  • Huge folders being scanned. Make sure node_modules, build output and data files are git-ignored.

Too many permission prompts

Every command asking for approval gets tiring. Instead of approving one by one:

  • Press Shift+Tab to switch to a mode that auto-approves edits.
  • Add allow rules for safe, repeated commands (npm test, git status) in .claude/settings.json. (Permission modes, settings explained)

Don't jump straight to skipping all permissions on your own machine. (dangerously-skip-permissions)

Claude ignores your instructions

  • Put durable rules in CLAUDE.md — short, specific, and in the project root. (How to write a CLAUDE.md)
  • If a rule must be followed every time (never edit .env, always run the formatter), use a hook, which runs regardless of what the model decides. (Claude Code hooks)
  • After a long session, instructions from early on may have been compacted away. Restate them, or start fresh.

It keeps breaking things while fixing things

That's a fix loop. Stop, rewind to before it started (Esc Esc), and give a clearer, narrower instruction — ideally with a failing test. (Stuck in an AI fix loop?)

The summary

  • Run claude doctor first.
  • "command not found" → new terminal, then PATH.
  • Login issues → check plan, /logout, stray ANTHROPIC_API_KEY.
  • Slow → background long commands, compact or clear context.
  • Ignored rules → CLAUDE.md for guidance, hooks for hard rules.

EasySpawn gives you a persistent server with Claude Code already installed and updated, so there's no local setup to troubleshoot — sign in with your own Claude subscription and start. See how it works or join the waitlist.

Related: How to Install Claude Code · Claude Code Usage Limits · Claude Code Keyboard Shortcuts · Resume a Claude Code Session

Keep reading