Introduction
You just typed a prompt into Claude Code, hit Enter, and… nothing. Or worse it ran, rewrote half your codebase, and now your app doesn't compile. If you're searching "claude code not working," you're not alone, and you're definitely not doing something obviously wrong.
Claude Code has become one of the most powerful AI coding assistants available to developers in 2026. But like any complex tool that runs in the terminal, connects to external APIs, manages file permissions, and maintains a 200K-token context window, things break. The frustrating part is that "not working" can mean ten different things, and each has a completely different fix.
This guide covers every major category of Claude Code failure you're likely to hit: installation errors, authentication problems, connection timeouts, context window exhaustion, out-of-scope file edits, permission denials, and runtime crashes. For each one, you'll get the exact symptom, the root cause, and the specific commands or configuration changes that resolve it. No filler. No generic advice about "restarting your computer."
Whether you're a developer who's been using Claude Code for months or someone who just installed it and can't get past the first prompt, this troubleshooting guide is built to get you back on track fast.
What "Claude Code Not Working" Actually Means
Before jumping into fixes, it helps to know what category of failure you're dealing with. Claude Code problems broadly fall into five buckets:
1. Installation / Environment errors The claude command doesn't exist, Node.js is the wrong version, or PATH isn't configured. These happen once during setup and block you entirely.
2. Authentication errors Your API key is missing, expired, or your Claude Max/Pro subscription isn't being recognized. Claude Code starts but immediately refuses requests.
3. Connection / Server errors 503, 529, or timeout errors from Anthropic's servers. These could be outages on Anthropic's end, rate limiting, or your local network blocking the API.
4. Behavioral errors Claude Code responds but does unexpected things: editing files you didn't mention, reverting changes it just made, forgetting earlier context, or getting stuck in loops.
5. Performance / Configuration issues Slow responses, context window filling up mid-task, settings not applying, or permission denials interrupting automated workflows.
Knowing which bucket you're in saves you from reinstalling the whole tool when you just need to clear your session, or waiting for a server outage to resolve when the actual problem is a missing environment variable.
Why Claude Code Breaks: Root Causes Explained
The Distributed Architecture Problem
Claude Code isn't a single service — it's a chain of components. Your terminal sends requests through an API gateway to inference servers, which return responses through a CDN layer. Any link in that chain can fail independently. That's why two developers can have completely different experiences at the same moment: one hits a regional server issue while the other works fine.
The Context Window Reality
Claude Code's context window is 200,000 tokens — large, but not unlimited. Long sessions, big codebases, and verbose prompts eat through it faster than most developers expect. When the window fills, Claude Code compacts conversation history automatically, and nuanced constraints or decisions you set early in the session may not survive that summary accurately.
The Agentic Scope Problem
Claude Code is designed to solve problems autonomously. That's its strength. It's also why it sometimes edits five files when you ask about one — it identified related code and "fixed" it without asking. Without explicit scope boundaries, the model acts on anything it determines is relevant.
Rate Limits vs. Real Outages
This trips up a lot of developers. When you hit your usage limit, you get an error that looks almost identical to a server-side failure. The distinction matters: one requires patience, the other requires adjusting your API plan or request patterns.
Symptoms Checklist: Identify Your Problem First
Before running fixes, match your symptom to a category:
Symptom | Most Likely Cause |
command not found: claude | Installation failure / PATH issue |
Invalid API key | Auth misconfiguration |
503 Service Unavailable | Server-side outage or overload |
529 Too Many Requests | Rate limiting |
Hangs with no response | Network issue or session state corruption |
Rewrites files you didn't mention | Scope / CLAUDE.md issue |
Forgets earlier constraints | Context compaction |
Reverts previous changes | Context conflict / missing git checkpoints |
Permission denied on file ops | Directory ownership or settings.json config |
Settings not applying | Settings scope conflict |
Step-by-Step Fix Guide
Fix 1: Installation Problems
Symptom: command not found: claude or claude: No such file or directory
Cause: The npm global install didn't complete, or your PATH doesn't include the npm global bin directory.
Fix:
# Step 1: Reinstall using the native installer curl -fsSL https://claude.ai/install.sh | bash # On Windows (PowerShell): irm https://claude.ai/install.ps1 | iex # Step 2: Verify installation which claude claude --version |
If the which claude command returns nothing after reinstalling, your PATH needs updating:
bash # Add to ~/.zshrc or ~/.bashrc export PATH="$HOME/.npm-global/bin:$PATH" source ~/.zshrc |
Node.js version error: Claude Code requires Node.js 18 or higher. Check and update:
bash node --version # Must be 18.0+ # Install latest LTS via nvm if needed curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.0/install.sh | bash nvm install --lts nvm use --lts |
EACCES permission error during install:
bash sudo chown -R $(whoami) ~/.npm npm install -g @anthropic-ai/claude-code |
Fix 2: Authentication Errors
Symptom: Invalid API key or Subscription not recognized
Cause: Your ANTHROPIC_API_KEY environment variable is missing, has extra whitespace, or your Claude Pro/Max session is expired.
Fix for API key errors:
bash # Reconfigure Claude Code interactively claude config # Or set the environment variable directly export ANTHROPIC_API_KEY="sk-ant-..." # No spaces, no quotes in value # Verify the key is set echo $ANTHROPIC_API_KEY |
Get a fresh API key from console.anthropic.com if needed. Make sure to add the export line to your shell config file (~/.zshrc or ~/.bashrc) so it persists across sessions.
Fix for subscription recognition issues:
Log out of Claude.ai completely in your browser
Clear browser cookies and cache
Log back in using incognito/private mode
Run claude config to re-authenticate the terminal client
Fix 3: Connection and Server Errors
Symptom: 503 Service Unavailable, 529 Too Many Requests, requests timing out, terminal hanging with no response
Step 1 — Check if it's Anthropic's side: Visit status.anthropic.com and check all service components, not just the top-level indicator. Specific API endpoints can fail while the overall status shows green. Also check the Anthropic Discord and X/Twitter for real-time developer reports.
Step 2 — Distinguish rate limiting from outages: A 529 means you've hit your usage limit. A 503 usually means server-side capacity issues. These require different responses — you can't fix a 503 by changing your code.
Step 3 — If it's a server issue: Wait 2–5 minutes. Don't reinstall. Don't regenerate your API key. These actions have no effect on server-side failures. Implement retry logic in automated pipelines:
bash # Simple retry pattern in bash scripts for i in 1 2 3 4 5; do claude "$PROMPT" && break echo "Attempt $i failed. Waiting ${i}0 seconds..." sleep $((i * 10)) done |
Step 4 — If your internet is the issue:
bash # Test connectivity to Anthropic ping api.anthropic.com curl -I https://api.anthropic.com # Check if a proxy or VPN is interfering # Try temporarily disabling and retesting |
Fix 4: Context Compaction and Forgotten Constraints
Symptom: Claude Code starts asking questions you already answered. It ignores constraints you set earlier. Code contradicts decisions made at the start of the session.
Cause: The context window filled and Claude Code automatically compacted the conversation. Earlier nuanced instructions didn't survive the summary accurately.
Immediate fix:
bash # Inside Claude Code, check current understanding "Summarize what we've built so far and what constraints are in place." # Correct any inaccuracies before continuing work # Use /compact proactively before the window fills /compact |
Prevention — the CLAUDE.md approach:
Create a CLAUDE.md file in your project root. This file is loaded fresh at the start of every session and survives compaction. Put your constraints here, not in the chat:
markdown # Project: MyApp ## Current State (updated: 2026-05-15) - Auth system: complete, do not modify - Payment flow: in progress, working on Stripe webhook - Cosmetics catalog: stable, do not touch ## Constraints - Do not modify files in /src/lib/ unless explicitly asked - Always use TypeScript strict mode - Database queries go through /src/db/client.ts only |
Fix 5: Revert Loops and Lost Work
Symptom: Claude Code implements a feature, you accept it, ask for something else, and previous changes disappear or get partially overwritten.
Cause: A later instruction conflicted with an earlier assumption, or Claude Code re-read a file and interpreted its state differently than what it wrote previously.
Fix:
bash # Step 1: Always commit after meaningful changes git add . && git commit -m "checkpoint: [feature name]" # Step 2: Diagnose what was reverted git diff HEAD~1 # Step 3: Restore specific reverted files git checkout HEAD~1 -- src/components/SomeFile.tsx |
Prevention: When issuing a new instruction, explicitly reference what should stay untouched: "Without changing src/auth/session.ts, add a logout button to the header component." This anchors Claude Code's context and prevents it from re-evaluating files that are already complete.
Fix 6: Out-of-Scope File Edits
Symptom: You asked about one component. Claude Code edited it correctly — but also refactored three other files, renamed a variable elsewhere, or restructured a utility you didn't mention.
Cause: Claude Code's agentic mode is designed to solve the full problem. Without scope constraints, it acts on anything it determines is relevant.
Fix:
bash # After any session, audit which files were changed git diff --name-only # Review unexpected changes before committing git diff src/utils/unexpectedFile.ts |
Prevention in prompts: Always name the specific file(s): "Only modify src/components/Button.tsx. Do not change any other files."
Prevention in CLAUDE.md:
markdown ## Off-Limits Files - Do not modify anything in /src/lib/ unless explicitly instructed - Do not rename variables across files without asking first - Do not touch /src/auth/ unless the task explicitly involves authentication |
Fix 7: Permission Denials
Symptom: Claude Code stops mid-task with Permission denied, can't read/write files, or asks for permission repeatedly on the same action.
Cause: Claude Code's permission system restricts certain actions by default. Inconsistent configuration between .claude/settings.json and actual file system structure causes unexpected blocks.
Fix — configure persistent permissions:
json // .claude/settings.json (project-level) { "$schema": "https://json.schemastore.org/claude-code-settings.json", "allowedTools": ["read_file", "write_file", "execute_bash"], "allowedDirectories": ["./src", "./tests", "./scripts"] } |
bash # Fix directory ownership issues sudo chown -R $(whoami) . ls -la # Verify permissions # Allow Claude Code to access the current directory claude --add-dir $(pwd) |
Settings scope priority (important to understand): Managed settings override Command line, which overrides Local, which overrides Project, which overrides User. If a setting refuses to change, a higher-scope config is overriding it. Check:
bash ls ~/.claude/settings.json # User-level ls .claude/settings.json # Project-level ls .claude/settings.local.json # Local override |
Fix 8: Slow Responses and Performance Issues
Symptom: Claude Code takes 30+ seconds per response, hangs, or produces incomplete outputs.
Fix — switch models for speed:
bash # Use Claude Sonnet 4 for faster turnaround on straightforward tasks claude --model claude-sonnet-4-20250514 |
Fix — compress context:
bash # Inside Claude Code /compact keep only function signatures and current errors |
Fix — start fresh when context is deeply polluted:
bash /clear # Clears conversation history inside Claude Code # Or exit and restart exit claude |
Common Mistakes That Make Things Worse
1. Reinstalling to fix server errors. A 503 or 529 is Anthropic's servers responding to you — the tool is working fine. Reinstalling changes nothing. Check the status page first.
2. Keeping constraints only in the chat. Anything you type in the conversation can be lost to context compaction. If a constraint matters, it belongs in CLAUDE.md.
3. Not using git checkpoints. Working with Claude Code without committing regularly is like driving without a seatbelt. Eventually you will regret it. Commit after every meaningful change.
4. Vague prompts with no scope. "Improve the checkout flow" will get you changes across ten files. "Add a loading spinner to CheckoutButton.tsx only" gets you what you actually want.
5. Ignoring the planned-changes preview. In interactive mode, Claude Code shows you what it intends to modify before it does it. Most developers skip past this. Don't. Read the file list. If you see unexpected files, cancel and refine the prompt.
6. Using --dangerously-skip-permissions habitually. This flag exists for legitimate automation workflows with a git safety net. Using it casually removes the guard rails that prevent unintended file modifications.
Pro Tips for Power Users
Set up a pre-session ritual. Before every Claude Code session on a complex project, run git add . && git commit -m "pre-session checkpoint". This costs 5 seconds and gives you a clean rollback point.
Use /compact proactively. Don't wait for automatic compaction to fire mid-feature. Run /compact between major tasks yourself — you get to control what gets compressed and when.
Write CLAUDE.md like a new hire's onboarding doc. It should explain the architecture, the active work, the off-limits zones, and the decisions already made. A developer reading it cold should understand what to build next and what to leave alone.
Separate concerns into sessions. Each Claude Code session should have one clear deliverable. "Implement the full user profile system" is a recipe for context overflow. "Add avatar upload to the existing profile form" is a session-sized task.
Version-pin your Claude Code install. Breaking changes between Claude Code versions are real. Check the changelog when updating and pin to stable releases in CI/CD pipelines:
npm install -g @anthropic-ai/claude-code@latest
claude --version # Note this after every update
Monitor your API usage. Log into console.anthropic.com and check your usage dashboard regularly. Hitting limits unexpectedly during a critical session is avoidable if you track consumption proactively.
Real Use Case: Recovering a Broken Feature After Claude Code Went Out of Scope
A developer building a personal finance app was reworking the challenge system — adding new types, wiring up edge cases. She finished, pushed her branch, opened the app, and found the Lights catalog (a completely separate feature she hadn't touched in months) was broken.
What happened: she'd asked Claude Code to "clean up the reward calculation logic." Claude Code found a shared utility function used by both the challenge system and the Lights catalog, refactored it for consistency, and broke the catalog's expected behavior in the process. The change was technically correct in isolation — the utility was cleaner — but it broke an integration she hadn't mentioned.
The recovery process:
bash # Step 1: Identify all changed files git diff --name-only HEAD~1 # Step 2: Spot the unexpected file # src/utils/rewardCalculator.ts was changed without instruction # Step 3: Review the specific change git diff HEAD~1 -- src/utils/rewardCalculator.ts # Step 4: Restore the utility to its previous state git checkout HEAD~1 -- src/utils/rewardCalculator.ts # Step 5: Re-implement the challenge system changes on top |
The prevention: She added this to her CLAUDE.md:
markdown ## Shared Utilities — Caution Required - /src/utils/rewardCalculator.ts is shared by 4 features - Do not modify shared utilities without explicitly naming them in the prompt - When changing reward logic, always ask which features use the affected utility |
After that change, Claude Code stopped touching shared utilities unless she explicitly said to.
Frequently Asked Questions
Your PATH isn't configured to include npm's global binary directory. Run which clause to check. If it returns nothing, add export PATH="$HOME/.npm-global/bin:$PATH" to your .zshrc or .bashrc file and reload your shell with source ~/.zshrc.
Check status.anthropic.com for real-time service status. Also search recent posts on Anthropic's Discord or X for developer reports — community verification often shows problems before the official status page updates. If only you're affected, it's likely a local configuration issue.
This is Claude Code's agentic behavior interpreting "solve the problem" broadly. Fix it by naming specific files in every prompt ("Only modify src/Button.tsx") and adding off-limits directories to your CLAUDE.md file.
Context compaction fired — Claude Code's 200K token context window filled up and it summarized earlier conversation history. Put constraints and project state in CLAUDE.md instead of the chat, so they survive compaction. Use /compact proactively between tasks to control when it happens.
This is rate limiting, not a service outage. You've exceeded your usage quota for the period. Check your limits at console.anthropic.com. For API users, implement exponential backoff. For Claude Max subscribers, the limits are much higher but still exist during heavy concurrent usage.
Commit your work after every meaningful change (git add . && git commit -m "checkpoint"). When prompting for the next task, explicitly state what should stay unchanged: "Without modifying src/auth/, add..." This anchors the context and prevents conflicting re-interpretations.
Settings follow a strict scope hierarchy: Managed > Command line > Local > Project > User. A setting in a higher-scope config is overriding yours. Check for a settings.local.json or a managed policy file. Run ls ~/.claude/settings.json and ls .claude/settings.json to see which files exist and compare their contents.
Advanced Debugging
When basic fixes don't resolve the issue, these diagnostic steps help identify what's actually going wrong.
Check Claude Code logs:
bash # View Claude Code debug output claude --debug # Pipe to a file for analysis claude --debug 2>&1 | tee debug.log |
Test API connectivity directly:
bash # Verify your API key works outside Claude Code -H "x-api-key: $ANTHROPIC_API_KEY" \ -H "anthropic-version: 2023-06-01" \ -H "content-type: application/json" \ -d '{"model":"claude-sonnet-4-20250514","max_tokens":10,"messages":[{"role":"user","content":"hi"}]}' |
A successful response confirms your API key and network are both working. If this fails but you have a key, it's either expired, has wrong permissions, or Anthropic's API is down.
Isolate the environment:
bash # Test Claude Code in a clean directory mkdir /tmp/claude-test && cd /tmp/claude-test git init echo "test" > test.txt claude "What files are in this directory?" |
If it works in the clean directory but not your project, the issue is project-specific — likely a CLAUDE.md misconfiguration, a .claude/settings.json conflict, or a permissions problem on specific directories.
Prevention: The Developer Workflow That Avoids 90% of Issues
Build these habits and most Claude Code troubleshooting disappears:
1.Commit before every session — a clean git state gives you full rollback capability
2.Update CLAUDE.md after every session — the model forgets, the file doesn't
3.Name specific files in every prompt — prevents out-of-scope edits
4.Use /compact between major tasks — you control the compaction, not the token counter
5.Check git diff --name-only after every session — catch unexpected changes before they compound
6.Monitor your API quota weekly — avoid surprise rate limits during critical work
7.Keep sessions task-sized — one deliverable per session, not one epic per session
Final Verdict
Claude Code not working is almost never a sign that the tool is fundamentally broken. In the vast majority of cases, there's a specific, fixable cause and it falls into one of the categories covered in this guide.
For about 90% of issues, the solution is one of five things: reinstall correctly with the native installer, reconfigure your API key, check the status page and wait during outages, use CLAUDE.md to persist constraints across context compaction, or commit with git and scope prompts to prevent revert loops and out-of-scope edits.
The remaining 10% multi-file corruption after context failures, CI/CD permission architecture, production-breaking scope escapes benefit from a human developer's eyes on the actual diff.
Claude Code is genuinely one of the best AI coding tools available right now. The developers who get the most out of it aren't the ones who never hit errors they're the ones who built the habits and configurations that keep those errors manageable when they do happen.
Schema FAQ (5 Questions for Rich Results)
bash { "@context": "https://schema.org", "@type": "FAQPage", "mainEntity": [ { "@type": "Question", "name": "Why is Claude Code not working?", "acceptedAnswer": { "@type": "Answer", "text": "Claude Code stops working for several reasons: installation issues (wrong Node.js version, PATH not set), authentication errors (missing or invalid API key), server-side outages (check status.anthropic.com), rate limiting (529 error), or behavioral issues like context compaction or out-of-scope edits. Identify which category applies before troubleshooting." } }, { "@type": "Question", "name": "How do I fix the 'command not found: claude' error?", "acceptedAnswer": { "@type": "Answer", "text": "Run the native installer: curl -fsSL https://claude.ai/install.sh | bash (macOS/Linux) or irm https://claude.ai/install.ps1 | iex (Windows). If the command still isn't found after installing, add the npm global bin directory to your PATH: export PATH=\"$HOME/.npm-global/bin:$PATH\" in your ~/.zshrc or ~/.bashrc file." } }, { "@type": "Question", "name": "How do I stop Claude Code from editing files I didn't ask about?", "acceptedAnswer": { "@type": "Answer", "text": "Name specific files in every prompt ('Only modify src/components/Button.tsx') and add off-limits directories to your CLAUDE.md file with a note like 'Do not modify files in /src/lib/ unless explicitly instructed.' Run git diff --name-only after each session to audit which files were changed." } }, { "@type": "Question", "name": "Why does Claude Code forget constraints mid-session?", "acceptedAnswer": { "@type": "Answer", "text": "Context compaction fires when the 200K token context window fills up. Earlier conversation history is summarized, and nuanced constraints may not survive the summary. Put all constraints and project state in a CLAUDE.md file in your project root — this file is loaded fresh each session and survives compaction." } }, { "@type": "Question", "name": "Is there a way to check if Claude Code is down right now?", "acceptedAnswer": { "@type": "Answer", "text": "Yes. Check status.anthropic.com for official real-time service status. Look at individual service components, not just the top-level indicator. Cross-reference with the Anthropic Discord or X (Twitter) where developer reports often appear before the status page updates." } } ] } |
Featured Snippet Answer
What to do when Claude Code is not working:
Run claude --version to confirm the install is intact
Run echo $ANTHROPIC_API_KEY to verify authentication
Check status.anthropic.com for server outages
Run /clear inside Claude Code to reset session state
Commit your work with git add . && git commit -m "checkpoint" and add constraints to a CLAUDE.md file in your project root
Most Claude Code failures fall into one of these categories: installation/PATH issues, expired authentication, server-side outages, context compaction, or out-of-scope agentic behavior. Each has a specific fix covered in detail above.