Debug Systematically

Follow a structured debugging process when encountering errors or unexpected behavior.

Debugging Process

1. Reproduce

Goal: Confirm the error consistently occurs

• •Run the failing command/test again
• •Document exact steps to reproduce
• •Note any error messages verbatim
• •Check if error is consistent or intermittent

Example:

# Reproduce the error
make test

# Document output
Error: undefined method 'foo' on line 42

2. Isolate

Goal: Narrow down to specific component/function

• •Identify which component is failing
• •Remove unrelated code to isolate issue
• •Check if error occurs with minimal input
• •Use binary search to find breaking change

Example:

# Test individual components
go test ./pkg/auth/handler_test.go -v -run TestLogin

# Isolate to specific function
go test ./pkg/auth -v -run TestLogin/valid_credentials

3. Hypothesize

Goal: Form testable theories about the cause

• •Based on error message, what could cause this?
• •What changed recently that might affect this?
• •What assumptions might be wrong?
• •What edge cases aren't handled?

Examples:

• •Hypothesis 1: Nil pointer - missing initialization
• •Hypothesis 2: Type mismatch - wrong function signature
• •Hypothesis 3: Race condition - concurrent access

4. Test Hypotheses

Goal: Verify each hypothesis systematically

• •Test one hypothesis at a time
• •Add logging/debugging to verify assumptions
• •Check related code for similar patterns
• •Look at test failures for clues

Example:

// Test hypothesis 1: nil pointer
if handler.service == nil {
    log.Printf("DEBUG: service is nil")
}

// Test hypothesis 2: check types
log.Printf("DEBUG: user type=%T, expected=*User", user)

5. Fix

Goal: Apply fix and verify it resolves the issue

• •Implement the fix for confirmed root cause
• •Run the originally failing test/command
• •Verify fix doesn't break other functionality
• •Clean up any debug logging

Example:

// Fix: Initialize service before use
func NewHandler() *Handler {
    return &Handler{
        service: NewAuthService(), // was missing
    }
}

6. Prevent

Goal: Add tests to prevent regression

• •Add test case for the bug
• •Add tests for related edge cases
• •Document the fix if non-obvious
• •Update error handling if needed

Example:

func TestHandlerWithNilService(t *testing.T) {
    // Ensure handler initialization is correct
    h := NewHandler()
    require.NotNil(t, h.service)
}

When NOT to Skip Steps

Don't jump to conclusions:

• •❌ "This must be a nil pointer, let me add a nil check"
• •✅ "Let me reproduce the error and check what's actually nil"

Don't make multiple changes at once:

• •❌ Change 3 things, then test
• •✅ Change one thing, test, then proceed

Don't assume error messages are wrong:

• •❌ "That error doesn't make sense, ignore it"
• •✅ "That error is telling me exactly what's wrong"

Tools for Debugging

Logging

log.Printf("DEBUG: variable=%+v", variable)

Debugging Tools

# Go
dlv debug ./cmd/app

# Node
node --inspect-brk app.js

# Python
python -m pdb app.py

Test Isolation

# Run single test
go test -v -run TestSpecificFunction
npm test -- --testNamePattern="specific test"
pytest tests/test_file.py::test_function

Example Workflow

Problem: Test failing with "unexpected nil pointer"

Step 1 - Reproduce:

make test
# Output: TestLogin: unexpected nil pointer at handler.go:42

Step 2 - Isolate:

go test ./pkg/auth -v -run TestLogin
# Isolated to auth package, Login function

Step 3 - Hypothesize:

• •H1: handler.service not initialized
• •H2: user.Session is nil
• •H3: request.Context() returning nil

Step 4 - Test:

// Add logging at handler.go:42
log.Printf("DEBUG: handler=%+v", handler)
// Output shows handler.service is nil

Step 5 - Fix:

// In NewHandler()
return &Handler{
    service: NewAuthService(), // Fix: was missing
}

Step 6 - Prevent:

func TestNewHandler(t *testing.T) {
    h := NewHandler()
    require.NotNil(t, h.service)
}

Benefits

• •Systematic approach prevents wasted effort
• •Confirms root cause before fixing
• •Prevents introducing new bugs
• •Documents debugging process for future reference