🐛 Debugging & Troubleshooting
Systematic approaches to finding and fixing bugs.
Debugging process
- Reproduce — Can you reliably trigger the bug?
- Isolate — Narrow down where the bug lives
- Understand — Read the code, understand the flow
- Hypothesize — Form a theory about the cause
- Test — Validate your hypothesis with minimal changes
- Fix — Apply the smallest correct fix
- Verify — Confirm the fix and check for regressions
- Document — Add a test, update docs if needed
Isolation techniques
- Binary search — Comment out half the code, see if bug persists
- Minimal reproduction — Strip everything until only the bug remains
- Git bisect — Find the commit that introduced the bug
- Logging — Add strategic log statements around the suspected area
- Breakpoints — Step through execution in a debugger
Common bug categories
| Category | Typical cause | How to find |
|---|---|---|
| Off-by-one | Loop bounds, array indexing | Edge case tests |
| Null reference | Missing null check, async timing | Stack trace, null assertions |
| Race condition | Concurrent access, async ordering | Stress tests, logs with timestamps |
| State mutation | Shared mutable state, side effects | Debugger, immutability |
| Config error | Wrong env var, missing secret | Check deployment config |
Debugging tools
- Browser DevTools — Network, console, breakpoints, performance
- Debugger — VS Code, Chrome DevTools, pdb, delve
- Logging — Structured logs with context (request ID, user ID)
- Profiler — CPU/memory profiling for performance bugs
- git bisect — Binary search through commit history
When you're stuck
- Explain the bug out loud (rubber duck debugging)
- Take a break — fresh eyes find bugs faster
- Read the error message carefully, including the full stack trace
- Check if the bug exists on main branch
- Search for the error message in issues/Stack Overflow