Debug

Systematically trace errors, unexpected behavior, or broken functionality to find root causes.

When to Use

• Error messages you don't understand

• Something that "just stopped working"

• Unexpected behavior (wrong data, missing UI, etc.)

• Build/test failures

• API returning wrong status codes

Instructions

1. Gather Context

Ask for or find:

• Error message (exact text, stack trace)

• What was expected vs what happened

• When it started (after a specific change? randomly?)

• Reproducibility (always? sometimes? specific conditions?)

2. Check Recent Changes

git log --oneline -10 git diff HEAD~3 --name-only

Did something change recently that could cause this?

3. Trace the Error

Follow the stack trace or data flow:

Error location → Called by → Called by → Entry point

For each step:

• Read the relevant code

• Identify what inputs it receives

• Check what could make it fail

4. Common Culprits

Runtime Errors

• Null/undefined access (Cannot read property 'x' of undefined )

• Type mismatches (expected string, got object)

• Missing environment variables

• Import/export mismatches

React Errors

• Hydration mismatch (server vs client render different)

• Hook rules violation (conditional hooks, wrong order)

• Missing key prop in lists

• State update on unmounted component

API Errors

• Wrong HTTP method

• Missing/malformed request body

• Auth token expired/missing

• CORS issues

• Database connection failed

Build Errors

• TypeScript type errors

• Missing dependencies

• Circular imports

• Invalid config (next.config, tsconfig, etc.)

Data Errors

• Schema mismatch (DB vs code)

• Timezone issues (UTC vs local)

• Encoding issues (UTF-8, JSON parsing)

• Stale cache

5. Isolate the Problem

Narrow down:

• Does it fail in all environments or just one?

• Does it fail for all users/data or specific cases?

• Can you reproduce with minimal code?

6. Verify the Fix

After fixing:

• Confirm the original error is gone

• Check for regressions (did fixing this break something else?)

• Add a test if appropriate to prevent recurrence

Output Format

Debug Report

Symptom: {what the user reported}

Root Cause: {what's actually wrong}

Trace:

1. {entry point} - {what happens here}
2. {next function} - {what happens here}
3. {failure point} - {why it fails}

Fix: {file}:{line} - {what to change}

Verification:

• Error no longer occurs
• Related functionality still works

Prevention: {Optional: test to add, validation to include, etc.}

Debugging Strategies

Binary Search

If you don't know where the bug is:

• Find a known-good state (commit, branch, or code path)

• Find the bad state

• Check halfway between

• Repeat until you find the breaking change

Rubber Duck

Explain the problem out loud (or to Claude):

• What should happen?

• What actually happens?

• What have you tried?

Often the act of explaining reveals the issue.

Add Logging

Temporarily add console.log at key points:

console.log('Function called with:', input) console.log('After transform:', result) console.log('Returning:', output)

Remove after debugging.

Check Assumptions

The bug is often in something you "know" is correct:

• That env var is set... is it?

• That function returns a string... does it?

• That data exists... does it?

Notes

• Start with the error message - it usually points close to the problem

• Don't guess - trace the actual code path

• If stuck after 15 minutes, step back and question assumptions

• Some bugs are environment-specific - check dev vs prod differences