Claude Code Troubleshooting: Every Common Error and How to Fix It

Claude Code is a powerful CLI tool, but it has its quirks. I've been using it daily for months and I've hit pretty much every error it can throw. This guide covers the most common issues developers face, with real error messages and actual fixes — no fluff.

ENOENT: No Such File or Directory

This is the single most common Claude Code error. It appears in multiple forms:

Error: ENOENT: no such file or directory, scandir '/Users/you/.claude/skills'

Or on Windows:

Error: ENOENT: no such file or directory, scandir 'C:\Users\you\.claude\skills'

What's happening: Claude Code tries to scan for a .claude/skills directory that doesn't exist yet. It uses readdirSync without checking if the directory is there first.

The fix: Create the missing directory:

# macOS / Linux
mkdir -p ~/.claude/skills

# Windows (PowerShell)
mkdir "$env:USERPROFILE\.claude\skills"

This has been a persistent bug across multiple versions (v2.1.17 through v2.1.20+). If you're hitting it, you're not alone — it's one of the most filed issues on the Claude Code GitHub repo.

Other ENOENT variants:

• Missing .claude directory entirely — run mkdir -p ~/.claude
• Project-level .claude directory issues — create .claude/ in your project root
• MCP log directory paths with colons on Windows — a known Windows-specific bug

MCP Server Configuration Errors

MCP (Model Context Protocol) servers extend Claude Code with external tools. They're brilliant when they work. Getting them to work is sometimes the challenge.

Servers Won't Connect

The most common MCP issue: servers that work independently but refuse to connect through Claude Code.

Things to check:

1. Timeout: MCP servers have a startup timeout. Increase it: MCP_TIMEOUT=10000 claude
2. JSON syntax: One misplaced comma in .mcp.json and nothing loads. Validate your JSON.
3. File location: .claude/.mcp.json sometimes doesn't load. Try moving config to .mcp.json in the project root.
4. Restart required: After editing MCP config, you must restart Claude Code. It doesn't hot-reload.

No Such Tool Available

You've configured an MCP server, it starts up, but Claude says the tools don't exist.

No such tool available: browser_navigate

Fix: This is usually a timeout issue. The server started but didn't register tools fast enough. Increase MCP_TIMEOUT or check your server's startup time. Use --mcp-debug flag for detailed logs.

Windows Path Issues

Windows paths with backslashes break MCP configs:

# Wrong — will fail
claude mcp add fs -- npx -y @modelcontextprotocol/server-filesystem C:\Users\you\Documents

# Correct — use forward slashes
claude mcp add fs -- npx -y @modelcontextprotocol/server-filesystem C:/Users/you/Documents

Too Many MCP Servers

Each MCP server's tool definitions consume context window space. When your tool descriptions eat more than 10% of the context window, Claude Code enables Tool Search mode, which dynamically loads tools on-demand. If you're not using a server, disable it: claude mcp remove <name>.

Context Window and Compaction Issues

This catches everyone eventually. You're deep into a complex refactor, and Claude starts forgetting things, giving generic responses, or losing track of what you asked.

Understanding What's Happening

Claude Code has a ~200K token context window. Every message, file read, command output, and tool result fills it up. When it hits ~95% capacity, auto-compact kicks in — summarising the conversation and replacing old messages.

The problem: compaction can happen mid-task, losing important context about what you were doing.

Auto-Compact Failed

The worst version of this:

Error: Conversation too long. Press esc twice to go up a few messages and try again.

When the previous message is itself a compaction summary, there's nothing to go back to. You're stuck.

Recovery:

1. Press Ctrl+C to halt
2. Start a fresh session: /quit then claude
3. Let Claude re-read your project files from scratch

Preventing Context Blowouts

Run /compact manually at natural breakpoints. Don't wait for auto-compact. After finishing a feature, fixing a bug, or reaching any logical stopping point — compact.

You can also guide what gets preserved:

/compact keep the architecture decisions and file structure we established

Use CLAUDE.md for persistent context. Anything Claude always needs to know — project structure, coding standards, common commands — put it in CLAUDE.md. It persists across compactions and new sessions.

Break large tasks into smaller sessions. If a task can't be done in one session, break it down. Before context runs out, ask Claude: "What problems did you run into that you wish you'd known about?" Save the answer, start fresh, and feed it back in.

Use .claudeignore. Exclude build artifacts, lock files, node_modules, and anything Claude doesn't need to read. Less noise = more useful context.

Hooks Not Working

Claude Code hooks let you run shell commands in response to events. They're powerful but finicky.

PreToolUse Hooks Never Fire

This is a known bug. PreToolUse and PostToolUse hooks sometimes don't execute at all, while other hook types (Stop, SubagentStop, UserPromptSubmit) work fine with identical config patterns.

Key gotchas:

• Use PascalCase: PreToolUse, not preToolUse. Wrong casing = silent failure.
• Template variables ({{tool.name}}, {{timestamp}}) may not interpolate — they appear as literal text.
• After changing hooks in .claude/settings.local.json, restart Claude Code. Changes may not take effect otherwise.
• Hook changes require review in the /hooks menu before they apply — this is a security feature.

Pre-Commit Hook Workaround

There's no native PreCommit hook event. The workaround: use PreToolUse with a Bash matcher, then parse $CLAUDE_TOOL_INPUT with jq to check if the command is git commit.

It's brittle. The cleaner approach: tell Claude about your pre-commit requirements in CLAUDE.md and use standard git hooks.

Permission Errors

Claude Code can't modify files it doesn't have permission to access. This sounds obvious but it trips people up in two ways:

Wrong Working Directory

If Claude Code is running but you haven't navigated to your project directory, every file operation fails. Always start Claude Code from your project root:

cd ~/projects/my-app
claude

System File Permissions

On macOS especially, directories like /Library/Application Support/ClaudeCode/ may have restricted permissions:

sudo chown -R $(whoami) ~/.claude

On Linux with global installs:

sudo chown -R $(whoami) /etc/claude-code/.claude

Installation and Update Issues

Node.js Version

Claude Code requires Node.js 18+. Check with:

node --version

If you're below v18, update via nvm, Homebrew, or your package manager of choice.

npm Permission Issues

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

Fix:

sudo chown -R $(whoami) ~/.npm

Or better — use nvm to manage Node.js installations, which avoids global permission issues entirely.

Corrupted Installation

When nothing else works, a clean reinstall fixes a surprising number of issues. Corrupted installations and permission errors account for a significant portion of unexplained crashes:

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

Rate Limits and API Errors

Rate Limit Exceeded

Rate limit exceeded. Please retry after X seconds.

This is straightforward — you're hitting the API rate limit. Wait and retry. If it's happening frequently, your conversation might be too large (each message sends the full context). Run /compact to reduce token usage.

API Key Issues

If you're getting authentication errors, verify your API key:

claude config

Check that your key is valid and your account has available credits.

Quick Diagnostic Checklist

When something's broken and you don't know where to start:

1. Run claude doctor — built-in diagnostics for your installation
2. Check Node.js version — must be 18+
3. Check internet connection — Claude Code needs API access
4. Verify API key — claude config
5. Try --verbose — detailed logging during operations
6. Try --mcp-debug — MCP-specific debugging
7. Check file permissions — ls -la ~/.claude
8. Clear and restart — /clear then /quit and relaunch

If you're still stuck, use /bug within Claude Code to report the issue with full context, or file an issue on the Claude Code GitHub repository.

Summary

Most Claude Code issues fall into a few categories: missing directories (create them), MCP configuration (validate JSON, increase timeouts, restart), context management (compact early and often), and permissions (check ownership). The tool is still evolving fast — updating to the latest version often fixes edge cases that haven't been formally documented yet.