Lesson 8: Troubleshoot — When Claude Gets Confused

Day 8 of 50 · ~10 min · Phase 1: Foundations

Why This Lesson Exists

Real learning happens when things break. In the first seven lessons, you've seen Claude Code working smoothly. But Claude isn't perfect — sometimes it misunderstands, reads the wrong file, or gets stuck.

This lesson presents three common failure scenarios you will encounter as a beginner. For each one, we'll walk through what went wrong, how to diagnose it, and how to fix it.

Scenario 1: Claude Misunderstands the Task

What happened: You asked Claude to "Add error handling to the login function," but Claude added error handling to the signup function instead.

What it looks like:

[You:] "Add error handling to the login function"

[Claude:] "I'll add try-catch blocks to the signup.js file."

[Claude makes edits to the wrong file]

[You:] "That's not right — I meant the login function!"

Diagnose it: What do you think went wrong?

Pause and think before reading on.

Claude probably made an assumption. Maybe:

• Your project has both login.js and signup.js
• Claude found "signup" first when searching for authentication functions
• Claude didn't read carefully enough to see that signup handles the login flow (confusing naming)
• You weren't specific enough about which file

The fix:

Stop the conversation and be more specific. Type:

Let me clarify: I'm talking about the login function in src/auth/login.js, 
which handles user authentication when they enter their password. 
Let's read that file first to make sure we're on the same page.

The lesson: This connects back to Lesson 2 (conversation mode) and Lesson 5 (strategic reading). Claude should have used Grep to search for "login" and asked you which one you meant if there were multiple options. When Claude doesn't do that, guide it:

• Ask Claude to read the specific file
• Ask Claude to explain what it's about to change before changing it
• Use file paths, not just function names

The conversation is iterative. If Claude went wrong, correct it and continue.

Scenario 2: Claude Reads the Wrong File

What happened: You asked Claude to "update the API routes," but Claude read the test file instead of the actual routes file.

What it looks like:

[Claude:] "I'm going to read the API routes file..."

[Claude reads src/api/__tests__/routes.test.js instead of src/api/routes.js]

[Claude:] "I see the routes are [misinterprets test mocks as actual routes]"

[Claude makes changes based on misunderstanding]

Diagnose it: What could cause this?

Pause and think before reading on.

Claude used Glob and probably found multiple files with "routes" in the name. Without more context, it grabbed one. Or:

• The filename was ambiguous
• Claude didn't ask you which file to use
• The Glob pattern was too broad

The fix:

When you see Claude reading the wrong file, say:

That's the test file. I need you to look at the production code instead.
The file is src/api/routes.js (not the __tests__ version).
Read that file and tell me what routes are defined there.

Then Claude will read the correct file and proceed.

The lesson: This reinforces Lesson 4 (tool transparency) and Lesson 5 (strategic reading). Because Claude shows you every tool call, you can catch mistakes before they happen. If Claude reads the wrong file, you see it in the conversation and can correct it immediately.

The superpower of tool transparency is that you're never surprised by what Claude did — you see it first.

Scenario 3: Claude Gets Stuck in a Loop

What happened: You asked Claude to "Refactor the authentication module," and Claude is now running the same test 5 times, making small fixes each time, unable to fix the underlying issue.

What it looks like:

[Claude:] "Let me run the tests to see what's failing..."
[Bash: npm test]
[Test fails with: "Cannot find module 'bcrypt'"]

[Claude:] "I'll add bcrypt to package.json"
[Edit: package.json]

[Claude:] "Let me run the tests again..."
[Bash: npm test]
[Same error]

[Claude:] "Let me try a different approach..."
[Repeats the same fix]

[This happens 5+ times]

Diagnose it: What's really happening here?

Pause and think before reading on.

Claude is looping but not making progress. The root cause is that bcrypt needs to be installed (npm install), not just added to package.json. Claude has the right idea but is missing a step.

This happens because:

• Claude is trying to fix things but not reasoning about root causes
• Claude doesn't ask for help when it's stuck
• Claude tries the same thing over and over

The fix:

Interrupt Claude and say:

I notice you're making the same edit repeatedly. Let me help:
The issue is that bcrypt isn't installed. You need to run npm install 
after editing package.json. Once bcrypt is actually installed, the tests should work.

Then Claude will:

• Run npm install
• Run the tests again
• See the real error (if there is one)
• Move forward

The lesson: This connects to Lesson 3 (the agentic loop) and Lesson 2 (conversation mode). The loop should include a "check" step where Claude verifies the fix worked. If the check shows the same problem, Claude should reason about why the fix didn't work instead of repeating it.

When Claude gets stuck, it's usually because:

1. Claude didn't reason about the root cause
2. Claude is trying the same thing twice
3. Claude needs clarification from you

Stop it and help. Say: "I see you're repeating the same fix. Let's think about this differently..."

Key Takeaway

The agentic loop is powerful, but it's not magic. When Claude misunderstands, reads the wrong thing, or gets stuck, the solution is usually to intervene in the conversation, provide clarification, and guide Claude toward the right path.

You're not in the passenger seat — you're the navigator. Claude does the driving, but you make sure it's going the right direction.

Quick Reference: When Things Go Wrong

A Final Thought

Claude Code is powerful because it can act. But that power means mistakes can happen faster than with a chatbot. The good news: because Claude shows you everything (Lesson 4 — tool transparency), you can catch and fix problems in real-time.

You've now completed Phase 1: Foundations.

You understand:

• What Claude Code is and why it exists (Lesson 1)
• How to install and authenticate it (Lesson 2)
• How the agentic loop works (Lesson 3)
• What tools Claude has (Lesson 4)
• How Claude reads code (Lesson 5)
• How to use it in practice (Lab, Lesson 6)
• What you learned (Checkpoint, Lesson 7)
• What to do when things go wrong (Lesson 8)

Phase 2 dives deeper into real workflows: making edits, working with git, writing effective prompts, and advanced techniques.

← Back to Curriculum · Lesson 9 →