Debugging

When to use this skill

• Encountering runtime errors or exceptions

• Code produces unexpected output or behavior

• Performance degradation or memory issues

• Intermittent or hard-to-reproduce bugs

• Understanding unfamiliar error messages

• Post-incident analysis and prevention

Instructions

Step 1: Gather Information

Collect all relevant context about the issue:

Error details:

• Full error message and stack trace

• Error type (syntax, runtime, logic, etc.)

• When did it start occurring?

• Is it reproducible?

Environment:

• Language and version

• Framework and dependencies

• OS and runtime environment

• Recent changes to code or config

Check recent changes

git log --oneline -10 git diff HEAD~5

Check dependency versions

npm list --depth=0 # Node.js pip freeze # Python

Step 2: Reproduce the Issue

Create a minimal, reproducible example:

Bad: Vague description

"The function sometimes fails"

Good: Specific reproduction steps

"""

1. Call process_data() with input: {"id": None}
2. Error occurs: TypeError at line 45
3. Expected: Return empty dict
4. Actual: Raises exception """

Minimal reproduction

def test_reproduce_bug(): result = process_data({"id": None}) # Fails here assert result == {}

Step 3: Isolate the Problem

Use binary search debugging to narrow down the issue:

Print/Log debugging:

def problematic_function(data): print(f"[DEBUG] Input: {data}") # Entry point

result = step_one(data)
print(f"[DEBUG] After step_one: {result}")

result = step_two(result)
print(f"[DEBUG] After step_two: {result}")  # Issue here?

return step_three(result)

Divide and conquer:

Comment out half the code

If error persists: bug is in remaining half

If error gone: bug is in commented half

Repeat until isolated

Step 4: Analyze Root Cause

Common bug patterns and solutions:

Pattern Symptom Solution

Off-by-one Index out of bounds Check loop bounds

Null reference NullPointerException Add null checks

Race condition Intermittent failures Add synchronization

Memory leak Gradual slowdown Check resource cleanup

Type mismatch Unexpected behavior Validate types

Questions to ask:

• What changed recently?

• Does it fail with specific inputs?

• Is it environment-specific?

• Are there any patterns in failures?

Step 5: Implement Fix

Apply the fix with proper verification:

Before: Bug

def get_user(user_id): return users[user_id] # KeyError if not found

After: Fix with proper handling

def get_user(user_id): if user_id not in users: return None # Or raise custom exception return users[user_id]

Fix checklist:

• Addresses root cause, not just symptom

• Doesn't break existing functionality

• Handles edge cases

• Includes appropriate error handling

• Has test coverage

Step 6: Verify and Prevent

Ensure the fix works and prevent regression:

Add test for the specific bug

def test_bug_fix_issue_123(): """Regression test for issue #123: KeyError on missing user""" result = get_user("nonexistent_id") assert result is None # Should not raise

Add edge case tests

@pytest.mark.parametrize("input,expected", [ (None, None), ("", None), ("valid_id", {"name": "User"}), ]) def test_get_user_edge_cases(input, expected): assert get_user(input) == expected

Examples

Example 1: TypeError debugging

Error:

TypeError: cannot unpack non-iterable NoneType object File "app.py", line 25, in process name, email = get_user_info(user_id)

Analysis:

Problem: get_user_info returns None when user not found

def get_user_info(user_id): user = db.find_user(user_id) if user: return user.name, user.email # Missing: return None case!

Fix: Handle None case

def get_user_info(user_id): user = db.find_user(user_id) if user: return user.name, user.email return None, None # Or raise UserNotFoundError

Example 2: Race condition debugging

Symptom: Test passes locally, fails in CI intermittently

Analysis:

Problem: Shared state without synchronization

class Counter: def init(self): self.value = 0

def increment(self):
    self.value += 1  # Not atomic!

Fix: Add thread safety

import threading

class Counter: def init(self): self.value = 0 self._lock = threading.Lock()

def increment(self):
    with self._lock:
        self.value += 1

Example 3: Memory leak debugging

Tool: Use memory profiler

from memory_profiler import profile

@profile def process_large_data(): results = [] for item in large_dataset: results.append(transform(item)) # Memory grows return results

Fix: Use generator for large datasets

def process_large_data(): for item in large_dataset: yield transform(item) # Memory efficient

Best practices

• Reproduce first: Never fix what you can't reproduce

• One change at a time: Isolate variables when debugging

• Read the error: Error messages usually point to the issue

• Check assumptions: Verify what you think is true

• Use version control: Easy to revert and compare changes

• Document findings: Help future debugging efforts

• Write tests: Prevent regression of fixed bugs

Debugging Tools

Language Debugger Profiler

Python pdb, ipdb cProfile, memory_profiler

JavaScript Chrome DevTools Performance tab

Java IntelliJ Debugger JProfiler, VisualVM

Go Delve pprof

Rust rust-gdb cargo-flamegraph

References

• Debugging: The 9 Indispensable Rules

• How to Debug

• Rubber Duck Debugging