Debugging & Troubleshooting Intermediate

Even the best AI assistant makes mistakes. Knowing how to quickly identify, diagnose, and recover from Claude Code issues is an essential skill. This guide covers the most common problems and their solutions.

Claude Makes Incorrect Edits

The most common issue. Claude edits a file but the change is wrong or breaks something.

# Undo the last change with git
$ git diff                    # See what changed
$ git checkout -- src/file.ts # Revert specific file
$ git stash                   # Stash all changes (can recover later)

# Then provide better instructions
> That edit was incorrect. The function should return a Promise, not a callback.
> Here's what the correct signature should look like:
> async function fetchUser(id: string): Promise<User>

Claude Doesn't Understand the Codebase

Symptoms: Claude creates files in wrong locations, uses wrong patterns, or misunderstands architecture.

Fix: Improve your CLAUDE.md

# Ask Claude to help improve its own context
> You just created a route handler in the wrong directory. Our routes go in
> src/routes/, not src/controllers/. Please update CLAUDE.md with the correct
> file structure so this doesn't happen again.

Claude Repeats the Same Mistake

When Claude keeps making the same error despite corrections:

1. Be more specific in your correction

   Instead of "that's wrong, try again," explain why it's wrong and what the correct approach is.

2. Provide an example

   Show Claude exactly what correct code looks like for your codebase.

3. Start a new session

   Sometimes context gets polluted with incorrect approaches. A fresh session with a better prompt often works.

4. Add the rule to CLAUDE.md

   If it's a recurring issue, add a specific instruction to prevent it in the future.

Permission Denied Errors

# Check Claude Code's permission settings
$ claude config list

# If Claude can't run certain commands, check allowed tools
$ claude --allowedTools "Read,Write,Edit,Bash,Grep,Glob"

# For file permission issues
$ ls -la src/  # Check file ownership
$ chmod -R u+rw src/  # Fix permissions if needed

Token Limit Reached

When Claude stops mid-response or says it can't continue:

# Compact the conversation to free up space
> /compact

# If that's not enough, start a new session
> /clear
# or exit and restart claude

# For future prevention: compact proactively every 10-15 turns

Slow Responses

The /doctor Command

Use /doctor to diagnose Claude Code configuration issues:

# Run diagnostics
> /doctor

# This checks:
# - API key validity
# - Network connectivity
# - Node.js version
# - Claude Code version
# - Configuration issues
# - Permission settings

Common Error Messages and Fixes

Recovery Checklist

When something goes wrong, follow this checklist:

1. Check git diff to see what changed
2. Revert unwanted changes: git checkout -- file
3. If the session is confused, try /compact or /clear
4. If the problem persists, start a new session with a better prompt
5. Update CLAUDE.md to prevent the issue in the future
6. If it's a Claude Code bug, check for updates: npm update -g @anthropic-ai/claude-code