Debugging with Claude Code

Use Claude Code to debug errors, analyze stack traces, find root causes, and fix bugs. Includes workflows for Python, JavaScript/Node.js, and general debugging patterns.

Claude Code works best for debugging when you give it the full error output and let it read the source files. Here are the most effective patterns.

Paste and fix

# Just paste the error directly — Claude reads the relevant files:

"I'm getting this error:

Traceback (most recent call last):
  File 'src/api/users.py', line 47, in create_user
    db.add(user_obj)
  File 'src/db/session.py', line 12, in add
    self.session.add(obj)
sqlalchemy.exc.IntegrityError: (psycopg2.errors.UniqueViolation)
    duplicate key value violates unique constraint 'users_email_key'

Fix it."

# Claude reads src/api/users.py, src/db/session.py, and the relevant models.
# It identifies: create_user doesn't check for existing email before insert.
# It implements: a check (or upsert) before db.add().

Run and iterate

# Let Claude run the failing test and iterate until it passes:

"Run pytest tests/test_users.py::test_create_duplicate_user
and fix the test or the code until it passes."

# Claude runs: pytest tests/test_users.py::test_create_duplicate_user -x
# Reads the failure output
# Reads the test and source files
# Implements a fix
# Runs again to verify
# Repeats until green

Root cause analysis for intermittent bugs

# For bugs that don't reproduce consistently:

"This error appears in production logs but I can't reproduce it locally:

KeyError: 'user_id'
  File 'src/middleware/auth.py', line 23, in get_current_user
    return request.state.user['user_id']

Check the code path and find all conditions where request.state.user
might not have a 'user_id' key."

# Claude traces the code path:
# - How is request.state.user set?
# - Under what conditions could 'user_id' be absent?
# - What middleware runs before auth.py?
# Returns a list of code paths that can trigger the bug.

JavaScript / Node.js debugging

# Paste the Node.js error:
"Fix this:

TypeError: Cannot read properties of undefined (reading 'map')
    at UserList (/src/components/UserList.jsx:14:22)
    at renderWithHooks (react-dom.development.js:14985:18)

The component is trying to render before data loads."

# Claude reads UserList.jsx, identifies the missing null check,
# and adds appropriate loading state handling.

# For async/Promise bugs:
"This Promise chain is not resolving correctly:
[paste code]
Find why the catch handler is never called."

Debug logging strategy

# Ask Claude to add strategic debug logging:
"Add debug logging to the payment processing flow in src/payments/
so I can trace the state at each step. Use Python logging, level=DEBUG,
and include the transaction_id in every log line."

# Remove it later:
"Remove all the debug logging you added in src/payments/"

# For production debugging without code changes:
"Show me how to enable verbose logging for SQLAlchemy without
changing application code (environment variable or config approach)."

Bisect a regression

# When a bug was introduced by a recent commit:

"This test was passing last week and now fails:
[test output]

Check git log for commits to src/auth/ in the last 7 days and
identify which commit likely introduced this regression."

# Claude runs:
# git log --oneline --since='7 days ago' -- src/auth/
# git show  for each candidate
# Reads the test to understand what it checks
# Identifies the most likely culprit commit

Common debugging patterns Claude handles well

For code review (catching bugs before they happen), see Claude Code code review workflow. For using hooks to automatically run tests after edits, see Claude Code hooks tutorial.

Frequently asked questions

Free tools

More examples