5 Common Claude Code Errors and How to Fix Them

There's a particular kind of frustration that comes from hitting the same error twice. Claude Code is remarkably capable, but if you use it every day, you'll encounter a handful of errors that show up again and again. I've been burned by each of these enough times to write them down.

1. Permission denied — Can't touch the file

When Claude Code tries to edit a file and gets blocked, it's usually one of two things.

Pattern A: Wrong file ownership

# Check who owns the file
ls -la config.json
# -rw-r--r-- 1 root root 1024 May  5 09:00 config.json
 
# Transfer ownership to yourself
sudo chown $(whoami) config.json
 
# Or for an entire directory
sudo chown -R $(whoami) ./your-project/

This happens most often with files generated inside Docker containers or copied with admin privileges. The fix is always the same: give yourself ownership.

Pattern B: CLAUDE.md allowedTools restriction

If your project has a CLAUDE.md at the root, check whether Write is listed under allowedTools.

# Missing Write permission
allowedTools:
  - Read
  # Write is not here — Claude can't edit files

Add Write to the list, or use --dangerously-skip-permissions for development work where tight restrictions aren't necessary.

2. RESOURCE_EXHAUSTED — Rate limit hit

Error: 429 RESOURCE_EXHAUSTED: Resource has been exhausted

The most common trigger: loading a large file and asking Claude to analyze the whole thing at once. One big request can consume thousands of tokens before you realize what happened.

Fix 1: Use /compact to compress the context

Run /compact inside Claude Code to summarize the conversation history and free up token headroom. This is usually the fastest recovery when a session starts feeling sluggish.

Fix 2: Narrow your requests

# Instead of: "Read this entire 3,000-line file and suggest improvements"
# Try: "Look at lines 120–180 in src/utils/auth.ts and check the token logic"

Smaller, focused requests hit limits far less often and tend to produce better answers too.

Fix 3: Wait 60 seconds

Rate limits typically reset within a minute. Retrying immediately just adds more requests to the queue. Step away, come back, try again.

3. MCP server not found — Server won't start

Error: MCP server 'filesystem' not found or failed to start

In my experience, the culprit is almost always the configuration file. Open it and look for this exact mistake:

cat ~/.claude/claude_desktop_config.json

// Wrong — "mcp-server-filesystem" isn't a system command
{
  "mcpServers": {
    "filesystem": {
      "command": "mcp-server-filesystem",
      "args": ["/Users/username/projects"]
    }
  }
}

Unless you've installed the package globally and it's on your PATH, this will fail silently. Use npx instead:

{
  "mcpServers": {
    "filesystem": {
      "command": "npx",
      "args": [
        "-y",
        "@modelcontextprotocol/server-filesystem",
        "/Users/username/projects"
      ]
    }
  }
}

After any change to this file, fully restart Claude Code. The config is only read on startup.

4. Context window exceeded — Too much history

Error: This model's maximum context length is 200000 tokens.
Your request has exceeded the limit.

Long sessions and large file loads are the usual culprits. The good news: it's mostly preventable with a few habits.

Prevention: Run /compact proactively

Don't wait until you hit the limit. After every 15–20 exchanges, run /compact to summarize the session. Claude keeps the important context and discards the redundant parts.

Prevention: Write context into CLAUDE.md

## Project overview
This is a Next.js app for managing user subscriptions.
 
## Current work in progress
Implementing webhook handling for Stripe payment events.
 
## Code conventions
- TypeScript strict mode
- Functional components only
- Tailwind for styling

When a session overflows and you need to start fresh, a well-written CLAUDE.md gets you back up to speed in seconds instead of minutes.

5. Bash command failed — Shell command errors

Error: Tool call failed: bash command failed with exit code 1

This one is almost never Claude's fault. It's an environment issue on your machine.

Common cause: PATH not inherited

Claude Code's shell sessions don't always inherit the PATH settings from your .zshrc or .bashrc. A command that works in your terminal might not be found in Claude's shell.

# This might fail if python3 isn't on Claude's PATH:
python manage.py migrate
 
# Better — be explicit about the full setup:
# "Run: python3 -m venv .venv && source .venv/bin/activate && pip install -r requirements.txt"

When giving Claude shell instructions, be specific about paths and activation steps. Remove any ambiguity about which Python, which node version, or which virtual environment to use.

Common cause: sudo required

For security reasons, Claude Code restricts sudo commands. If a step requires elevated permissions, run it manually in your terminal first, then let Claude continue from there.

Five errors, five patterns. Once you recognize them, you spend less time searching for answers and more time actually building things. If MCP connection issues keep coming up for you, there's a deeper look at the diagnostic process in the premium guide — but the config file and restart cycle alone will solve most cases.

Start with /compact. Use it more than you think you need to. Context overflow is the one error that's purely habitual, and the habit is easy to fix.