Claude Code Troubleshooting

Step-by-step fixes for the most common Claude Code errors, slowdowns, and configuration issues.

Jump to your problem above, or scan the error messages table if you have a specific error string. Most issues fall into one of three root causes: credentials, context size, or permissions.

1. Authentication & API Key Errors

Invalid API key / 401 Unauthorized

Common trap: copying an API key from a web page can add a leading/trailing newline. Always paste into a plain text editor first, strip whitespace, then set it.

API key works but Claude Code shows "unauthorized" in IDE

IDE extensions (VS Code, JetBrains) read credentials from a different location than the CLI. Run claude auth status in a terminal opened from the IDE. If the terminal shows a different user than the web UI, log in again: claude auth logout && claude auth login.

Rate limit errors (429 Too Many Requests)

Billing & quota errors

Check your usage and limits at console.anthropic.com → Usage. If you've hit a prepaid credit limit, add more credits. If you're on a subscription, check monthly spend limits. Claude Code's pricing page has a full breakdown of what each request type costs.

2. Installation & Setup Issues

Command not found: claude

Permission denied during npm install

npm error EACCES: permission denied, mkdir '/usr/local/lib/node_modules'

Don't use sudo with npm. Instead, configure npm to use a user-local prefix:

mkdir -p ~/.npm-global
npm config set prefix '~/.npm-global'
echo 'export PATH=~/.npm-global/bin:$PATH' >> ~/.bashrc
source ~/.bashrc
npm install -g @anthropic-ai/claude-code

Or use a Node version manager (nvm, fnm, volta) — they install to your home dir and avoid permission issues entirely.

Claude Code won't update / stuck on old version

npm update -g @anthropic-ai/claude-code
claude --version

If the version still doesn't change, the old binary may be cached in a different location. Find it: which claude — if the path doesn't match your npm global bin, uninstall and reinstall:

npm uninstall -g @anthropic-ai/claude-code
npm install -g @anthropic-ai/claude-code

macOS: "claude" can't be opened because it is from an unidentified developer

This applies to the desktop app, not the npm package. Right-click the app → Open → Open anyway. Or run: xattr -dr com.apple.quarantine /Applications/Claude\ Code.app.

3. Slow Responses & Hanging

Claude Code is slow on every request

Cause	Diagnosis	Fix
Large context window	claude --debug shows token count >50K	/compact or start fresh session
Wrong model	claude config get model shows opus	Switch to sonnet or haiku for simple tasks
Network latency	Ping api.anthropic.com >200ms	Use a VPN to a US server, or accept latency
Reading huge files	Claude reads node_modules or dist/	Add .claudeignore
API outage	Errors across all requests	Check status.anthropic.com

Claude hangs with no output for >60 seconds

Press Ctrl+C to interrupt. Then:

1. Run claude --debug <same request> to see verbose logs — look for where it's blocked.
2. If the hang is on a tool call (Bash, Read, MCP), the tool itself may be hanging. Test the tool call directly.
3. Disable MCP servers one by one (claude mcp remove <name>) to identify if an MCP server is hanging during connection.
4. Check if a pre-tool hook is blocking: look for PreToolUse hooks in .claude/settings.json that run commands with infinite loops or wait for input.

Claude reads the same large file repeatedly (burning tokens)

Claude re-reads files whose content might change between turns. To stop this, add stable large files to .claudeignore (same syntax as .gitignore):

# .claudeignore
node_modules/
dist/
build/
*.lock
*.log
coverage/
.next/

Claude will still know these paths exist (from ls), but won't read their contents unless you explicitly ask.

4. Context Length & Memory Issues

Context length exceeded

The 200K token limit for claude-sonnet-4-6 is roughly 500–600KB of combined text (source files + conversation). A large React codebase with 100 files averages 50–80KB — well within limits unless Claude reads all of them in one session.

Claude "forgot" something I told it earlier in the session

This is a compaction side-effect, not a bug. When /compact runs (automatically or manually), it summarizes old turns. Details that seemed minor may get dropped. Strategies:

• Put important constraints in CLAUDE.md — it's read fresh every session and never compacted away.
• Repeat key constraints at the start of each task: "Remember: don't modify test files."
• Use Projects to persist instructions across sessions automatically.

Claude ignores my CLAUDE.md instructions

Check the following:

• File is named CLAUDE.md (case-sensitive on Linux/macOS).
• File is in the project root — the directory where you run claude, not a subdirectory.
• Run claude --print-config to confirm it's being loaded.
• Keep CLAUDE.md under 2000 words — very long files risk partial reads during compaction.
• Start instructions with imperative verbs: "Always use TypeScript strict mode" is clearer than "TypeScript strict mode is preferred".

5. Permission & Tool Errors

Tool call blocked by permission system

Permanently allow a tool or command pattern in .claude/settings.json:

{
  "allowedTools": [
    "Read",
    "Glob",
    "Grep",
    {"name": "Bash", "allowedCommands": ["npm test", "npm run build", "git status", "git diff"]}
  ]
}

Or use the /permissions command in Claude Code to add rules interactively. See the full permissions guide for project vs. global settings.

Claude refuses to delete / overwrite files

Claude Code's defaults are conservative around destructive operations. To allow file deletion:

{
  "allowedTools": [
    {"name": "Bash", "allowedCommands": ["rm -f src/old-module.ts"]}
  ]
}

For broad file deletion in a specific directory, consider using a script that Claude can call instead of raw rm commands — this gives you a clear audit trail.

Permission denied when running scripts (chmod issues)

If Claude tries to run a script but gets permission denied:

# Claude can run this to fix it
chmod +x scripts/deploy.sh

Or add a Make target that Claude can call without needing chmod. Pre-chmod your script files once, then add them to your allowed Bash commands list.

Claude won't push to git / run destructive git commands

This is intentional — Claude Code does not auto-push or force-push by default. To allow git operations:

{
  "allowedTools": [
    {"name": "Bash", "allowedCommands": ["git add", "git commit", "git push origin"]}
  ]
}

6. MCP Server Problems

Diagnosing MCP connection failures step by step

1. List servers: claude mcp list — shows each server and its status (connected / error).
2. Test a specific server: claude mcp test <server-name>
3. Run the server manually: Copy the command from ~/.claude/mcp_settings.json and run it directly in a terminal. Watch stderr for startup errors.
4. Check binary exists: which <server-binary> or node <server-path>.
5. Re-add the server: claude mcp remove <name> && claude mcp add <name> <command>.

MCP server crashes immediately

Common causes: missing environment variables, wrong Node.js version, missing npm packages. Check:

# Run the server manually with verbose output
node /path/to/mcp-server/index.js 2>&1

If it requires environment variables (API keys, DB URLs), add them to the env field in mcp_settings.json:

{
  "mcpServers": {
    "my-db": {
      "command": "node",
      "args": ["/path/to/server.js"],
      "env": {"DATABASE_URL": "postgres://..."}
    }
  }
}

MCP tools show up but return errors

After the server connects, tool call errors usually mean the server received valid JSON but its internal logic failed. Enable debug logging in the MCP server itself (check its README), then watch the server's stderr while Claude makes a tool call. The error will be in the server process, not in Claude Code.

MCP server works in terminal but not in Claude Code

Claude Code may launch the server with a different working directory or PATH. In mcp_settings.json, set cwd explicitly:

{
  "mcpServers": {
    "my-server": {
      "command": "/usr/local/bin/node",
      "args": ["/absolute/path/to/server.js"],
      "cwd": "/absolute/path/to/server/"
    }
  }
}

7. Hook Failures

My hook never runs

Check placement in .claude/settings.json:

{
  "hooks": {
    "PreToolUse": [
      {"matcher": "Bash", "hooks": [{"type": "command", "command": "echo 'pre-bash hook'"}]}
    ]
  }
}

Verify: (1) The event name matches exactly (PreToolUse, PostToolUse, PreCompact, Stop); (2) The matcher matches the tool name Claude is calling; (3) The JSON is valid (run jq . .claude/settings.json).

Hook is blocking Claude Code from proceeding

If a PreToolUse hook exits with a non-zero code, Claude treats it as a permission denial and won't call the tool. Run the hook command manually to see what it's returning. Temporarily disable it:

# Comment out the hook entry in settings.json to disable
# { "type": "command", "command": "..." }  ← disable by removing or commenting

Hook runs but Claude doesn't see its output

Hooks communicate with Claude via stdout (structured JSON). If a hook writes to stderr or doesn't emit JSON, Claude won't see it. Format your hook output:

#!/bin/bash
# Example PreToolUse hook that adds context
echo '{"type":"context","content":"Current git branch: '$(git rev-parse --abbrev-ref HEAD)'"}'

See the full hooks guide for all output formats.

8. Common Error Messages Reference

Error	Root cause	Quick fix
401 invalid x-api-key	Wrong or revoked API key	claude config set api_key <key>
429 rate_limit_exceeded	Too many requests / quota exhausted	Wait and retry; upgrade tier
ContextLengthExceeded	Prompt + history > 200K tokens	/compact then retry
command not found: claude	npm global bin not in PATH	Add npm bin dir to PATH
EACCES permission denied	npm install needs sudo (don't)	Use nvm or fix npm prefix
Tool call blocked by permission system	Tool not in allowedTools	Add to settings.json allowedTools
MCP server failed to start	Binary missing or env var unset	Run server manually to see error
Cannot read properties of undefined	Stale Claude Code version bug	npm update -g @anthropic-ai/claude-code
Connection refused (MCP)	MCP server not running	Restart server; check port
CLAUDE.md not loaded	Wrong filename or wrong directory	Check case, run from project root
CompactionError	Context too large to compact	/clear and start fresh
Model not found	Model ID string is wrong	Use exact ID: claude-sonnet-4-6

FAQ

Does Claude Code work offline?

No — Claude Code requires an internet connection to call the Anthropic API. There is no local inference mode. If you need offline AI coding, look at locally-run models (Ollama + Continue, LM Studio) as an alternative, though they are significantly less capable than Claude Sonnet/Opus.

Why does Claude keep asking me to confirm the same Bash command?

Because that command pattern is not in your allowedTools list. Add it to .claude/settings.json once and Claude will stop asking. See the permissions guide.

Claude is writing code in the wrong language / wrong style

This is a CLAUDE.md issue. Add a style section:

# Code Style
- Language: TypeScript (strict mode)
- Formatter: Prettier (run automatically)
- Testing: Jest, never mock the database
- No inline comments unless the WHY is non-obvious

Claude Code works in terminal but not in VS Code

The VS Code extension and the CLI use separate credential stores. Run claude auth status in both the VS Code integrated terminal and a standalone terminal to compare. If different, re-authenticate in VS Code: open the Command Palette → "Claude Code: Sign in".

Claude is generating the same response over and over (loop)

This happens when Claude gets confused in a long session — usually because it lost track of what's already been done. Interrupt with Ctrl+C, run /clear, and restart with a fresh, explicit prompt about the current state.

My .gitignore patterns aren't working in .claudeignore

.claudeignore uses standard gitignore syntax but is evaluated independently of git. Double-check: (1) No trailing spaces; (2) Directory patterns end with / (e.g. node_modules/); (3) The file is at the project root; (4) Negation patterns (!important-file.ts) work only if a broader pattern already excluded it.

How do I completely reset Claude Code configuration?

# Remove all Claude Code config (credentials, settings, memory)
rm -rf ~/.claude

# Reinstall
npm install -g @anthropic-ai/claude-code
claude auth login

Why is Claude Code more expensive than expected?

The three biggest cost drivers: (1) Large context — each token in the prompt is charged, so reading big files repeatedly is expensive; use .claudeignore aggressively; (2) Opus instead of Sonnet — Opus is 5× more expensive; switch with --model claude-sonnet-4-6 for most tasks; (3) Prompt cache misses — if you start many short sessions, you pay full price every time; longer sessions with /compact amortize the cost better. See the pricing calculator for exact numbers.

Still stuck?

• Run claude --debug <your request> — verbose output usually shows exactly where it's failing.
• Check the official Claude Code docs for up-to-date release notes.
• Search or post in the Anthropic Discord — #claude-code channel.
• File a bug at github.com/anthropics/claude-code/issues.

Related Guides

• Setup & Installation — fresh install walkthrough
• Permissions Guide — full allowedTools reference
• Memory & CLAUDE.md — how to persist instructions
• Claude Code Hooks — event-triggered shell commands
• MCP Servers — adding and configuring MCP integrations
• Pricing & Cost Management — understanding API costs
• Best Practices — CLAUDE.md, TDD, context management
• All Claude Code Skills — full directory

More Claude Code Tools

• Claude Code Cost Calculator →Paste a session log, see exact $ cost.
• AI Diff Summarizer →Git diff → plain-English PR description.
• Prompt Improver →Paste a prompt, get a refined version back instantly.
• Claude API Cookbook →Long-tail guides for Claude API usage.