Fix Claude Code Errors Fast

When Claude Code stops working

Something broke. Maybe Claude Code hit a rate limit, ran out of context, or threw an error you haven't seen before. You need a fix, not a tutorial.

This guide covers the most common Claude Code errors, what causes them, and the exact steps to resolve each one. Bookmark it, you'll come back.

Rate limit errors

The most frequent Claude Code error is the rate limit. You'll see messages like "rate limit exceeded," "too many requests," or Claude simply pausing mid-task.

Why it happens

Anthropic enforces per-minute and per-day token limits based on your plan tier. Heavy sessions, large file reads, long conversations, rapid-fire commands, burn through limits fast. Opus uses roughly 3x the tokens of Sonnet for the same task, so model choice directly affects how quickly you hit the ceiling.

How to fix it

Immediate relief:

• Wait 60 seconds. Most per-minute limits reset automatically.
• Switch to a lighter model. If you're on Opus, drop to Sonnet for routine tasks.
• Clear your session with /clear or restart Claude Code to reduce accumulated context.

Prevent future hits:

• Use Haiku for simple searches and formatting tasks.
• Read specific line ranges instead of entire files (Read file.ts lines 50-100 instead of the whole file).
• Clear context between major tasks, don't run ten unrelated operations in one session.

For a deeper dive into rate limit management and plan-specific thresholds, see our rate limit fix guide.

Context window overflow

When Claude's context fills up, you'll notice degraded output quality before an outright error. Symptoms include: Claude forgetting instructions from earlier in the conversation, repeating itself, missing obvious details, or producing shorter and less accurate responses.

Why it happens

Every message, file read, tool output, and system prompt consumes tokens. A typical session starts with ~20% of the context window used by system prompts and CLAUDE.md. Each large file read can consume 5-10% more. After 30+ tool calls, you're often past 70% utilization.

When the window fills completely, Claude Code triggers auto-compaction, it summarizes earlier context to free space. This preserves the conversation but loses detail.

How to fix it

When you notice quality dropping:

1. Save any important state to a file (memory note, daily note, scratchpad).
2. Start a fresh session. Your CLAUDE.md and memory files reload automatically.
3. Reference the saved state to pick up where you left off.

Prevent overflow:

• Read only the lines you need, not full files.
• Avoid pasting large blocks of text into the chat.
• Use context management strategies like task-based session boundaries.
• Run /compact to force compaction before quality degrades, rather than waiting for auto-compaction.

Warning signs to watch:

• You've been in the same session for 40+ minutes of active work.
• You've read more than 3 files over 500 lines each.
• Claude starts asking questions it already answered earlier.

Permission denied errors

Claude Code operates within a permission system that controls which tools it can use and which files it can access. Permission errors fall into two categories: tool permissions and file system permissions.

Tool permission errors

You'll see "permission denied" when Claude tries to use a tool that hasn't been approved. This is by design, Claude Code asks for permission before running potentially dangerous operations.

Fix: When Claude asks for permission, review the action and approve it. If you want to pre-approve certain tools, configure your .claude/settings.json:

{
  "permissions": {
    "allow": [
      "Read",
      "Glob",
      "Grep",
      "Bash(git:*)",
      "Bash(npm:*)"
    ],
    "deny": [
      "Bash(rm:*)",
      "Bash(sudo:*)"
    ]
  }
}

This pre-approves safe tools while explicitly blocking dangerous ones. See our permissions guide for complete configuration options, or Claude Code permission errors for the allow list patterns that fix specific "tool not allowed" messages.

File system permission errors

If Claude can't read or write a file, the issue is OS-level. Common causes:

• The file is owned by root (e.g., files in /etc/ or created with sudo).
• The file has restrictive permissions (chmod 400).
• The directory doesn't exist yet.

Fix: Check permissions with ls -la and adjust with chmod or chown as needed. For new files, ensure the parent directory exists.

Hook failures

Hooks are shell scripts that run at specific lifecycle points. When a hook fails, the behavior depends on the hook type and your configuration.

PreToolUse hook blocks an action

If a PreToolUse hook exits with a non-zero code, the action is blocked. Claude sees the error output and tries to adjust. This is usually intentional: the hook is doing its job.

When it's not intentional:

1. Check the hook script for bugs. A syntax error or missing dependency causes unexpected blocks.
2. Test the hook in isolation:

echo '{"tool_input": {"file_path": "test.txt"}}' | .claude/hooks/your-hook.sh
echo $?

3. Verify your settings.json is valid JSON, malformed JSON silently breaks all hooks:

python3 -c "import json; json.load(open('.claude/settings.json'))"

Hook script not found

If the hook path in settings.json doesn't match the actual file location, the hook silently fails. Double-check:

• The path is relative to the project root.
• The script has execute permissions (chmod +x).
• The shebang line is correct (#!/bin/bash).

Hook causes infinite loops

A PostToolUse hook that triggers the same tool it monitors can create a loop. For example, a hook on Write that writes a log file, which triggers the hook again.

Fix: Add a check in the hook to exclude its own log file, or use the matcher field to narrow the scope so the hook only fires on specific files.

For more on configuring and debugging hooks, see our hooks documentation.

MCP connection issues

MCP (Model Context Protocol) servers extend Claude Code with external integrations, databases, APIs, cloud services. Connection failures are common, especially after restarts or configuration changes. For a dedicated, in-order walkthrough of every cause, see Claude Code MCP not connecting.

Server not responding

Symptoms: Claude says it can't reach a tool, or MCP tool calls hang indefinitely.

Fix:

1. Check if the MCP server process is running:

ps aux | grep mcp

2. Restart the specific server:

claude mcp restart <server-name>

3. Verify the server configuration in .mcp.json, especially API keys, URLs, and auth tokens.

Authentication failures

MCP servers that connect to external APIs (Meta, Airtable, Google Sheets) require valid tokens. Tokens expire. When they do, every tool call to that server fails.

Fix: Check token expiry, regenerate if needed, and update .mcp.json. Most tokens last 60-90 days. Set a calendar reminder to rotate them before expiry.

Server crashes on startup

If an MCP server fails to start, it's usually a dependency issue. Check:

• Node.js version compatibility (most servers need Node 18+).
• Required npm packages are installed in the server's directory.
• Environment variables referenced by the server are set.

Run the server manually to see its error output:

npx @your-mcp-server/package 2>&1

Claude Code won't start

If the problem is that the install itself never completed (an EACCES wall, a command not found, a Node version error), that is a different class of issue covered in Claude Code installation failed. If Claude Code is installed but won't launch, work through these checks:

1. Node.js version: Claude Code requires Node 18 or later. Check with node --version.
2. npm installation: Verify the installation: npm list -g @anthropic-ai/claude-code.
3. API key: Ensure your Anthropic API key is set. Claude Code reads it from the ANTHROPIC_API_KEY environment variable or from its config file.
4. Network: Claude Code needs internet access to reach Anthropic's API. Check your connection and any proxy/VPN settings.
5. Reinstall: If all else fails: npm uninstall -g @anthropic-ai/claude-code && npm install -g @anthropic-ai/claude-code@latest.

Session state corruption

Occasionally, stale state files from a previous session can cause unexpected behavior, gates that shouldn't be active, counters that are wrong, or hooks referencing files that no longer exist.

How to fix it

1. Delete stale gate files: rm -f /tmp/claude-*.gate
2. Clear the session: start a fresh Claude Code session.
3. If the problem persists, check .claude/settings.json for syntax errors, a single missing comma can break everything.

Error patterns by symptom

Quick reference when you know the symptom but not the cause:

Symptom	Likely cause	Fix
Claude pauses mid-response	Rate limit	Wait 60s or switch model
Output quality suddenly drops	Context overflow	Clear session, start fresh
"Permission denied" on tool use	Tool not approved	Approve or pre-approve in settings
Hook blocks an action unexpectedly	Hook bug or JSON error	Test hook in isolation
MCP tool call hangs	Server not running	Restart MCP server
Claude forgets earlier instructions	Context compacted	Save state, restart session
Claude Code won't launch	Node/npm/API key issue	Check prerequisites

FAQ

Why does Claude Code keep hitting rate limits even after I wait?

Per-minute limits reset quickly, but daily limits accumulate. If you've been running heavy sessions all day, you may hit a daily cap that only resets at midnight UTC. Switch to lighter models (Sonnet or Haiku) for routine tasks to stretch your daily budget further.

Can I increase my Claude Code rate limits?

Rate limits are tied to your Anthropic plan tier. Higher plans (Team, Enterprise) have higher limits. You can also optimize usage by reading fewer tokens per session, targeted line-range reads, clearing context between tasks, and using the right model for each task all reduce token consumption without requiring a plan upgrade.

How do I know if my context window is full?

Claude Code doesn't show a percentage meter. Watch for behavioral signals: shorter responses, missed instructions, repetitive output, or Claude asking about something you already told it. When you see these signs, clear the session. Running /compact proactively after complex tasks helps prevent silent degradation.

---

Most Claude Code errors come down to five things: rate limits, context overflow, permissions, broken hooks, or MCP configuration. Now you know how to fix all of them.

Still spending time troubleshooting instead of building? Claudify ships with pre-configured hooks, permissions, and MCP setups that prevent most of these errors from occurring in the first place.