Claude Code Troubleshooting
This page covers non-error issues: Claude Code running slowly, refusing to start, producing wrong output, ignoring your instructions, or behaving unexpectedly. If you are looking for specific error codes and messages, see the Error Handling reference instead.
Every issue below links to a detailed troubleshooting guide with verified solutions.
Performance Issues
When Claude Code feels slow, the problem is usually token-heavy context, network latency, or suboptimal configuration. These guides help you identify and fix the bottleneck.
- Fix Claude Code Slow Response – general slow response diagnosis
- Fix: Claude Code Slow Response Latency – latency-specific troubleshooting
- Fix Slow Response Latency – network and API latency fixes
- Speed Up Claude Code on Large Repos – large codebase optimization
- Make Claude Code Consider Performance – forcing performance-aware code generation
- Claude Code MCP tools loading slowly – MCP tool initialization delays
- Find Performance Bottlenecks – systematic performance profiling
- Claude Skills Slow Performance Speed-Up Guide – skill-specific performance tuning
Installation Problems
Installation failures prevent Claude Code from running at all. These guides cover every platform and package manager.
- Install Claude Code – canonical installation guide
- Claude Code Setup on Mac – macOS-specific installation steps
- Fix ‘command not found’ After Install – PATH configuration issues
- Fix Claude Command Not Found After Install – extended PATH troubleshooting
- claude: command not found After Install – binary location issues
- Fix zsh: command not found: claude – zsh-specific shell configuration
- PATH Not Updated After Install – manual PATH repair
- Fix Claude Code Install Killed on Linux – low-memory Linux installation
- Apple Silicon Rosetta Crash Error – M1/M2/M3 chip compatibility
- Claude Code Bun Install Setup Guide – Bun runtime installation
CLAUDE.md Not Working
The most frustrating category: you wrote a CLAUDE.md but Claude Code ignores it, reads it partially, or applies conflicting rules.
- Claude Code Ignoring CLAUDE.md Entirely – Claude not reading your config at all
- Fix How To Fix Claude Code Ignoring My CLAUDE.md – systematic debugging checklist
- CLAUDE.md Not Loading in Claude Code – file location and naming issues
- Fix Claude Md Not Being Read By Claude Code – parsing and detection problems
- CLAUDE.md Being Partially Read – truncation and token limit issues
- Fix Claude Md Changes Not Taking Effect – stale cache and reload issues
- Fix Conflicting CLAUDE.md Instructions – contradictory rule resolution
- Claude Code CLAUDE.md Not Found Fix – parent directory search behavior
Unexpected Behavior
Claude Code works but produces wrong output, modifies files you did not mention, or ignores your explicit instructions.
- Why Is Claude Code Changing Files I Did Not Mention? – unwanted file modifications
- Fix Claude Code Touching Unrelated Files – surgical change debugging
- Fix Claude Code Changing Indentation – style drift prevention
- Fix Claude Code Forgetting Variable Names – context window loss
- Claude Code Keeps Suggesting The Same Broken Solution – escaping solution loops
- Fix Claude Code Suggesting Wrong Framework – framework confusion
- Make Claude Code Explain Its Changes – forcing change explanations
- Fix Claude Code Poor Variable Naming – improving generated code quality
- Claude Code Breaks Existing Tests After Changes – preventing test regressions
IDE Integration Issues
Problems specific to VS Code, JetBrains, Neovim, and other editors.
- Fix Claude Code Not Working in VS Code – VS Code integration troubleshooting
- Fix Claude Code Not Working VSCode – alternative VS Code fixes
- Fix Claude Code Crashing in VS Code – VS Code crash recovery
- VS Code Extension Host Crash Fix – extension host process failures
- Claude Code + WebStorm JetBrains Setup – JetBrains IDE integration
- How to Set Up Claude Code in Ghostty – Ghostty terminal configuration
Authentication and Login Issues
Problems connecting Claude Code to your Anthropic account or API.
- Fix Claude Code OAuth Login Paste Not Working – browser-to-terminal auth flow
- Fix: Claude Code Auth Fails on Headless Linux – headless server authentication
- Fix: Claude Isn’t Working Right Now – service availability troubleshooting
- Claude Code Not Working After Update – post-update breakage recovery
- Fix Claude Code Not Responding Terminal Hangs – terminal freeze during authentication
Skill and Tool Issues
Problems with Claude Code skills, custom commands, and tool integrations.
- Fix Claude Skill Not Triggering Automatically – skill activation failures
- Claude Code Crashes When Loading Skill – skill load crashes
- Fix Claude Code Output Formatting Broken – output rendering issues
- Fix Bash Command Not Found in Skills – skill environment problems
- Claude Code Skill Permission Denied – skill execution permissions
- Fix Claude Tool Use Not Working – tool invocation failures
- Fix Claude Extended Thinking Not Working – extended thinking activation issues
- Fix Claude Streaming Not Working – streaming output failures
Docker and Container Issues
Troubleshooting Claude Code inside Docker containers, dev containers, and WSL.
- Fix Docker Networking with Claude Code – container networking
- How to Run Claude Code in Docker – Docker setup guide
- How to Use Claude Code with WSL2 – Windows Subsystem for Linux
- How to Use Dev Containers with Claude Code – devcontainer.json configuration
- Fix Claude Code Python Venv Not Detected – Python virtual environment detection
Interactive Diagnostic Tool
For issues not covered above, use the Claude Code Diagnostic Tool. It walks you through a decision tree that identifies your problem category, narrows the root cause, and links to the specific fix.
Frequently Asked Questions
Why is Claude Code so slow?
Three common causes: oversized context (too many files loaded), network latency to the Anthropic API, and MCP server initialization overhead. Start by checking your CLAUDE.md size and excluding unnecessary directories. See Fix Claude Code Slow Response.
Claude Code says ‘command not found’ after I installed it. What do I do?
Your shell PATH does not include the Claude Code binary location. Run which claude to check, and add the npm global bin directory to your PATH. The fix differs between bash, zsh, and fish shells. See Fix ‘command not found’.
Why does Claude Code ignore my CLAUDE.md file?
Four common reasons: the file is in the wrong directory (must be in the project root or a parent directory), the file has a casing mismatch (must be CLAUDE.md, not claude.md), the file exceeds the token limit (split it), or a cached version is being used. See CLAUDE.md Not Loading.
Claude Code keeps modifying files I did not ask about. How do I stop it?
Add explicit scoping rules to your CLAUDE.md: “Only modify files I explicitly mention” and “Never touch files in /config, /migrations, or /generated.” The Surgical Changes guide covers this in depth.
How do I fix Claude Code in VS Code?
First, check that the extension is updated. Then verify your API key configuration. If Claude Code crashes the extension host, disable other extensions one-by-one to find conflicts. See Fix Claude Code Not Working in VS Code.
Can I use Claude Code on a headless server?
Yes. Claude Code supports headless authentication via API key environment variables. Set ANTHROPIC_API_KEY in your environment and use --dangerously-skip-permissions for non-interactive mode. See Headless Linux Auth.
Why does Claude Code keep suggesting the same broken solution?
Claude Code lacks persistent memory of failed attempts within a session context. Explicitly tell it “That approach failed because [reason]. Try a different approach.” Adding failure context to your prompt breaks the loop. See Keeps Suggesting Same Broken Solution.
How do I troubleshoot MCP server connections?
Check the server process status, verify transport configuration (stdio vs HTTP), test the connection independently, and review timeout settings. The MCP Server Incident Response Guide provides a complete diagnostic workflow.
Explore More Guides
- Error messages and how to fix them
- Configuration and settings reference
- Prevent issues with best practices
- Installation and setup guide
- Advanced patterns for complex issues
Beyond Troubleshooting
This page helps you fix what is broken. The Claude Code Mastery Playbook ($99) helps you build systems that rarely break in the first place, with 200 production-tested practices covering prevention, monitoring, and recovery.