RaheesAhmed/debugger

Advanced Debugging

Debugging Methodology

The Scientific Method for Bugs

1. OBSERVE    — What exactly is happening? (error message, behavior, repro steps)
2. HYPOTHESIZE — What could cause this? (list 3+ possibilities)
3. TEST       — How to verify/eliminate each hypothesis?
4. ISOLATE    — Create minimal reproduction
5. FIX        — Make the smallest change that fixes the issue
6. VERIFY     — Confirm fix, add regression test, check for side effects

Priority: Read Before You Touch

ALWAYS read in this order:
1. The exact error message / stack trace
2. The file + line number from the stack trace
3. The surrounding context (function, imports, state)
4. Recent changes to the file (git log -5 --follow -- file.ts)
5. Related tests (if they exist)

THEN form a hypothesis. NEVER change code before understanding the error.

Error Analysis Patterns

Stack Trace Interpretation

TypeError: Cannot read properties of undefined (reading 'map')
    at UserList (src/components/UserList.tsx:15:22)       ← WHERE (component + line)
    at renderWithHooks (node_modules/react-dom/...)       ← React internals (ignore)
    at mountIndeterminateComponent (...)                   ← React internals (ignore)

Translation:
- In UserList.tsx, line 15, something is undefined
- .map() is called on undefined → an array is expected but not received
- Check: What variable is on line 15? Where does it come from? (props? state? API?)

Common Error Patterns

| Error | Usually Means | Fix | |-------|--------------|-----| | Cannot read property of undefined | Accessing nested object without null check | Optional chaining ?. or guard check | | X is not a function | Wrong import, stale reference, or wrong type | Check import path and export name | | ECONNREFUSED | Target server not running | Check if the service is running on the expected port | | ENOENT: no such file | File path is wrong | Check path construction, working directory | | MODULE_NOT_FOUND | Package not installed or wrong path | Run npm install or fix import path | | Unhandled Promise Rejection | Missing .catch() or try/catch | Wrap in try/catch, add error handler | | CORS error | Server doesn't allow origin | Configure CORS middleware on server | | hydration mismatch | Server/client render different HTML | Check for browser-only APIs, use useEffect |

Network Debugging

API Issues

1. Check the request:
   - Is the URL correct? (typos, wrong base URL, missing path segments)
   - Are headers correct? (Content-Type, Authorization)
   - Is the body correct? (JSON.stringify, form encoding)

2. Check the response:
   - What status code? (400 = your request is wrong, 500 = server bug)
   - What's in the response body? (error message, validation details)
   - Are there CORS headers? (Access-Control-Allow-Origin)

3. Reproduce with curl:
   curl -X POST https://api.example.com/endpoint \
     -H "Content-Type: application/json" \
     -H "Authorization: Bearer $TOKEN" \
     -d '{"key": "value"}'

WebSocket Debugging

// Add connection lifecycle logging
ws.addEventListener("open", () => console.log("[WS] Connected"));
ws.addEventListener("close", (e) => console.log(`[WS] Closed: code=${e.code} reason=${e.reason}`));
ws.addEventListener("error", (e) => console.error("[WS] Error:", e));
ws.addEventListener("message", (e) => console.log("[WS] Received:", e.data.slice(0, 200)));

Node.js Debugging

Memory Leak Hunt

# Start with --inspect and use Chrome DevTools
node --inspect dist/index.js

# Take heap snapshots via Chrome DevTools:
# 1. Open chrome://inspect
# 2. Click "inspect" on your Node process
# 3. Go to Memory tab → Take heap snapshot
# 4. Wait, take another snapshot
# 5. Compare snapshots → find growing objects

CPU Profiling

# Generate CPU profile
node --prof dist/index.js
# Process the log
node --prof-process isolate-*.log > profile.txt
# Look for "ticks" — functions that consumed the most CPU

Event Loop Monitoring

const THRESHOLD_MS = 100;
let lastCheck = Date.now();

setInterval(() => {
  const now = Date.now();
  const delay = now - lastCheck - 1000;
  if (delay > THRESHOLD_MS) {
    logger.warn(`Event loop blocked for ${delay}ms`);
  }
  lastCheck = now;
}, 1000);

React Debugging

Common React Issues

Infinite re-render:
  → Check useEffect dependencies — missing dep causes stale closure,
    adding object dep without useMemo causes infinite loop

Component not updating:
  → Check if you're mutating state (arrays, objects) instead of creating new references
  → obj.key = value (BAD) vs {...obj, key: value} (GOOD)

"Too many re-renders":
  → Calling setState during render, not in a handler
  → onClick={doSomething()} vs onClick={() => doSomething()}

Database Debugging

Slow Query Investigation

-- PostgreSQL: find slow queries
SELECT query, calls, mean_exec_time, total_exec_time
FROM pg_stat_statements
ORDER BY mean_exec_time DESC LIMIT 10;

-- Explain any slow query
EXPLAIN (ANALYZE, BUFFERS, FORMAT TEXT) SELECT ...;

-- Check index usage
SELECT schemaname, relname, seq_scan, idx_scan
FROM pg_stat_user_tables
WHERE seq_scan > idx_scan AND n_live_tup > 1000;

Git Bisect (Finding Regression)

# Start bisect
git bisect start
git bisect bad           # Current commit is broken
git bisect good v1.2.0   # Last known good version

# Git checks out a middle commit — test it
npm test
git bisect good  # or git bisect bad

# Repeat until Git identifies the exact breaking commit
# Then: git bisect reset

Debugging Rules

• NEVER change code before understanding the error
• ALWAYS reproduce the bug before attempting a fix
• Log MORE, not less — structured logging with context
• One change at a time — verify after each change
• If it takes > 30 min, step back and re-read the error message
• Write a regression test BEFORE fixing the bug
• Check if the bug exists in a fresh environment