Debugging with Claude Code¶

Learn systematic approaches to finding and fixing bugs with Claude Code.

What You'll Learn¶

Debugging methodology
Providing error context
Tracing issues
Fixing common bug types

The Debugging Process¶

Claude helps at every stage:

Reproduce - Understand when the bug occurs
Locate - Find where in the code the problem is
Diagnose - Understand why it's happening
Fix - Implement the solution
Verify - Confirm the fix works

Providing Error Context¶

The Gold Standard¶

Give Claude: - The exact error message - The stack trace - What you were doing when it happened - What you expected to happen

> I get this error when I submit the login form:

  TypeError: Cannot read property 'email' of undefined
    at validateUser (src/services/auth.js:45:23)
    at handleLogin (src/controllers/auth.js:12:15)
    at Layer.handle (node_modules/express/lib/router/layer.js:95:5)

  Expected: Login should work with email "test@example.com"
  Actual: 500 error returned

Quick Debug¶

For simpler issues:

> This function returns undefined instead of the user object:

  function getUser(id) {
    const user = users.find(u => u.id = id);
    return user;
  }

(Claude spots the = vs === bug immediately)

Locating Issues¶

When You Know the Area¶

> The bug is somewhere in the checkout process.
  Help me trace through checkout.js to find the issue.

When You Don't Know¶

> Users report that sometimes their cart empties randomly.
  Where should I look for this issue?

Claude searches for: - Cart-related code - State management - Session handling - Potential race conditions

Using Error Messages¶

> This error mentions line 45 of auth.js but I think the
  real problem is earlier. Help me trace back.

Common Bug Patterns¶

Null/Undefined Errors¶

> TypeError: Cannot read property 'name' of undefined

  The error is on this line:
  console.log(user.name);

Claude checks: - Where user comes from - What could make it undefined - Suggests null checks or fixes

Async Issues¶

> My function returns undefined even though the database
  query returns data. Here's the code:

  function getUsers() {
    let users;
    db.query('SELECT * FROM users', (err, result) => {
      users = result;
    });
    return users;
  }

Claude identifies the async timing issue.

Type Mismatches¶

> I'm passing a number but the function expects a string.
  Where is the type mismatch happening?

Logic Errors¶

> This loop should run 10 times but only runs 9:

  for (let i = 1; i < 10; i++) {
    console.log(i);
  }

State Issues¶

> The React component shows stale data even after the
  API call completes. Here's my useEffect...

Debugging Sessions¶

Session 1: Runtime Error¶

> When I run npm start, I get:

  Error: Cannot find module './config/database'

  But the file exists. Why can't Node find it?

Claude investigates: - File path and location - Import statement - File extension issues - Module resolution

Session 2: Logic Bug¶

> The discount calculation is wrong.
  - Cart total: $100
  - Discount: 20%
  - Expected: $80
  - Actual: $120

  Find the bug in calculateTotal()

Claude reads the function and finds the logic error.

Session 3: Integration Issue¶

> The API works fine when I test it directly, but fails
  when called from the frontend. CORS is configured.
  What else could cause this?

Claude explores: - Headers - Request format - Authentication - Proxy settings

Debugging Techniques¶

Add Logging (Temporarily)¶

> Add console.log statements to trace the flow through
  the checkout process. I'll run it and share results.

Isolate the Problem¶

> Let's test the database query separately from the API
  endpoint to isolate where the issue is.

Check Assumptions¶

> I assumed the user object always has an email.
  Check if there are cases where it might not.

Binary Search¶

> The bug was introduced between these two commits.
  Help me identify which files changed.

Fixing Bugs¶

Simple Fix¶

> Fix the null pointer error by adding a guard clause

With Context¶

> Fix this bug, but make sure we handle the case where
  the user is logged out too.

Minimal Change¶

> Fix this with the smallest possible change.
  Don't refactor anything else.

With Tests¶

> Fix the bug and add a test case that would have caught it

Verifying Fixes¶

Run Tests¶

> Run the tests related to authentication

Manual Check¶

> The fix looks good. What edge cases should I manually test?

Regression Check¶

> Could this fix break anything else?

Try It Yourself¶

Exercise: Debug This Code¶

A user reports that this function doesn't work:

async function getUserPosts(userId) {
  const user = await db.users.findById(userId);
  const posts = await db.posts.find({ author: user.id });
  return posts.map(post => {
    title: post.title,
    content: post.content,
    authorName: user.name
  });
}

Start Claude Code
Share this code
Ask Claude to find the bugs (there are multiple!)
Have Claude fix them
Ask what tests should cover this function

Exercise: Production Bug¶

Simulate a production debugging scenario:

Create a file with intentional bugs
Pretend you only have the error message (not the code visible)
Work with Claude to:
Locate the bug
Understand the cause
Implement a fix
Write a test

Pro Tips¶

Don't truncate error messages. Claude needs the full context.

Describe the Environment¶

> This works locally but fails in production.
  Production uses Node 16, PM2, and Redis.

Mention Recent Changes¶

> This started after we upgraded to React 18.

Be Honest About Attempts¶

> I tried adding try/catch but that just hides the error.
  I need to fix the root cause.

What's Next?¶

Master git workflows with Claude Code in 03-git-workflows.

Summary: - Provide complete error messages and stack traces - Follow the reproduce → locate → diagnose → fix → verify cycle - Claude can identify common patterns: null errors, async issues, type mismatches - Use logging and isolation to narrow down issues - Always verify fixes don't introduce regressions

Learning Resources¶

Featured Video¶

GitHub: GitHub for Beginners: TDD with Copilot (Official GitHub channel)

Learn systematic debugging approaches with AI assistance including error analysis and verification.

Additional Resources¶

Type	Resource	Description
🎬 Video	Claude Code Debugging Tips	Edmund Yong - Debug workflows
📚 Official Docs	Troubleshooting Guide	Official debugging documentation
📖 Tutorial	GitHub Debugging Guide	AI-assisted debugging patterns
🎓 Free Course	Microsoft Copilot Course	Free 10-hour debugging course
💼 Commercial	GitHub Copilot Pro	Advanced debugging techniques