Skip to main content

Troubleshooting

As you use Claude Code, you'll run into unexpected behavior, repeated mistakes, and dead ends. This chapter covers the most common problems and proven solutions.

Problem 1: Claude Keeps Repeating the Same Mistakeโ€‹

Symptom: Even after you ask for a fix, it generates the same incorrect code in the same way.

Cause: A bad pattern has accumulated in the conversation context, or the request is ambiguous.

Solutions:

# Method 1: Reset the context
> /clear

# Method 2: Point out exactly what's wrong
> The code you generated earlier has [specific problem].
  Rewrite it using [correct approach].
  In particular, never do [specific part] using [wrong approach].

# Method 3: Provide an example
> Follow this pattern:
  [correct code example]
  Implement [new feature] the same way.

Prevention: Document forbidden patterns in CLAUDE.md:

## Forbidden patterns
- No callbacks โ†’ use async/await
- No var โ†’ use const/let
- No any type โ†’ use precise type inference

Problem 2: Claude Modifies Files You Didn't Want Touchedโ€‹

Symptom: It changes files you never asked about.

Cause: The scope of the request was unclear, or Claude made extra changes it thought would be "helpful."

Solutions:

# Restrict the scope explicitly
> Only modify src/services/user.service.ts.
  Don't touch any other files.

# Review the plan before changes
> Before actually making changes, first tell me which files
  you plan to modify.

Prevention: List protected files in CLAUDE.md:

## Do-not-modify files
- src/config/ (configuration files)
- *.lock files
- src/generated/ (auto-generated code)

Problem 3: A Build/Test Error Occurs and Claude Can't Fix Itโ€‹

Symptom: Even when shown the error, it keeps making the wrong fix over and over.

Solutions:

# Step 1: Pass along the entire error, verbatim
> I'm getting this error:
  [full error message]

  Related files:
  [file contents]

# Step 2: Ask for the root cause first
> Before fixing anything, first explain the root cause of this error.

# Step 3: Approach it step by step
> Start with the simplest possible fix that just makes the error go away.
  We'll improve code quality afterward.

When stuck, change direction:

# Throw away the current code and start over
> /clear
> Implement [the feature] completely from scratch.
  Don't reference the existing code โ€” build it correctly from the start.

Problem 4: The Context Gets Too Long and Response Quality Dropsโ€‹

Symptom: The longer the conversation, the more it ignores earlier requests or loses consistency.

Cause: The context window fills up and early instructions get diluted.

Solutions:

# Reset the current context
> /clear

# Restart with only the essentials summarized
> Summary of work so far:
  - Done: [completed work]
  - In progress: [current work]
  - Remaining: [remaining work]
  Continue with [next task].

Prevention: For long tasks, run /clear at each checkpoint:

[Feature A done] โ†’ git commit โ†’ /clear โ†’ [start Feature B]

Problem 5: Claude Changes Too Much at Onceโ€‹

Symptom: Beyond what you asked, it "improves" several other files too.

Solutions:

# Restrict it explicitly
> Only modify exactly what I asked for. No other "improvements."

# Ask for minimal change
> Just fix this bug. With the smallest possible change.

# Review changes first
> Show me the diff of what you'll change before actually modifying anything.

Problem 6: API Key Errors / Authentication Problemsโ€‹

Symptom: Authentication error or Invalid API key errors.

Solutions:

# Check the API key
echo $ANTHROPIC_API_KEY

# Reset the API key
export ANTHROPIC_API_KEY="sk-ant-..."

# Or save it to ~/.claude/.env
echo "ANTHROPIC_API_KEY=sk-ant-..." >> ~/.claude/.env

Problem 7: It's Too Slowโ€‹

Symptom: Responses take a long time, or you wait too long on tool-call approvals.

Solutions:

# 1. Use a faster model
claude --model claude-haiku-4-5-20251001 "quick task"

# 2. Change the permission mode (auto-approve file edits)
# VSCode: Settings โ†’ Claude Code โ†’ Permission Mode โ†’ acceptEdits

# 3. Run in headless mode
claude --print "quick query" < input.txt

Problem 8: The Generated Code Doesn't Workโ€‹

Symptom: The code Claude wrote has errors.

A systematic debugging approach:

# Step 1: Pass along the error message
> Running this code produced the following error:
  [error details]
  [stack trace]

# Step 2: Provide environment info
> My environment is Node.js 20, TypeScript 5.3.
  I'm using these package versions: [package.json contents]

# Step 3: Minimal reproduction case
> I can reproduce the error with this minimal code:
  [minimal repro code]

Problem 9: A Hook Isn't Workingโ€‹

Symptom: You configured a Hook in settings.json but it never runs.

How to debug:

# Validate the settings.json syntax
cat ~/.claude/settings.json | python -m json.tool

# Test the hook command directly
echo "test" > /tmp/test.ts
npm run lint /tmp/test.ts

# Restart Claude Code
# (VSCode extension: Command Palette โ†’ "Claude Code: Restart")

Common mistake:

// Wrong
{
  "hooks": {
    "PostToolUse": {
      "matcher": "Write",  // โŒ must not be wrapped in an object
      "hooks": [...]
    }
  }
}

// Correct
{
  "hooks": {
    "PostToolUse": [       // โœ… must be an array
      {
        "matcher": "Write",
        "hooks": [...]
      }
    ]
  }
}

Problem 10: MCP Server Connection Failureโ€‹

Symptom: An MCP server won't connect, or its tools are unavailable.

Debugging:

# List servers
claude mcp list

# Check a server's status
claude mcp get <server-name>

# Run the server directly to test it
node /path/to/mcp-server.js

Common causes:

  • Missing environment variables (API keys, connection strings)
  • Wrong path to the server executable
  • Node.js version mismatch

An Effective Help-Request Templateโ€‹

How to communicate a problem to Claude precisely:

> The situation:
  [what you were trying to do]

  The error:
  [full error message]

  Related code:
  [filename]: [relevant code]

  What I've already tried:
  [attempted solutions]

  Expected behavior:
  [description of the correct behavior]

Escape Strategies When You're Stuckโ€‹

When nothing works:

  1. /clear and restart โ€” remove context contamination
  2. Break it into smaller pieces โ€” focus on "just this one function"
  3. Ask for a different approach โ€” "Implement this in a completely different way"
  4. Solve part of it yourself, then ask for review โ€” write some of it by hand and ask "is this direction right?"
  5. Reference the official docs โ€” give Claude the official documentation URL
The most important principle

When you're stuck, don't repeat the same method. Changing your approach is far more effective.

Last updated on