1. OBSERVE — Reproduce the issue reliably\n2. HYPOTHESIZE — Form the simplest explanation consistent with symptoms\n3. PREDICT — \"If my hypothesis is correct, then X should be true\"\n4. TEST — Run an experiment to falsify the hypothesis\n5. CONCLUDE — If wrong, refine hypothesis and repeat\nNever jump to a fix before you understand the cause. A fix without understanding is guessing.
\nYou cannot debug a bug you cannot reproduce.
\n# Note the exact conditions:\n# - Input / request body\n# - Environment (local / staging / prod)\n# - User account or data state\n# - Frequency (always / sometimes / once)\n# - When it started (after which deploy?)\n\n# Find the last good commit\ngit bisect start\ngit bisect bad HEAD\ngit bisect good v1.2.3 # last known good tag\n# git bisect then checks out midpoints — test and mark good/bad\nError: Cannot read properties of undefined (reading 'email')\n at UserService.findOneOrFail (/src/users/users.service.ts:42:23)\n at UsersController.findOne (/src/users/users.controller.ts:28:31)\n at ...\n\nReading strategy:\n1. Top line: the actual error — read it carefully word by word\n2. First frame after your code: where it crashed (users.service.ts:42)\n3. Frame above that: what called it (users.controller.ts:28)\n4. Ignore node_modules frames unless diagnosing a library issue\n// users.service.ts line 42 — the crash site\nasync findOneOrFail(id: number): Promise<User> {\n const user = await this.repo.findById(id)\n // line 42: user is undefined, not null — we expected null\n return user // accessing .email somewhere downstream fails\n}\n\n// Fix: repo.findOne returns undefined when not found, but our types say null\n// The contract mismatch is the root cause, not the downstream access\nBinary search through the call stack to find where the invariant breaks.
\n// Add strategic logging — not everywhere, but at the boundary\nasync findOneOrFail(id: number): Promise<User> {\n console.log('[DEBUG] findOneOrFail called with', { id, type: typeof id })\n const user = await this.repo.findById(id)\n console.log('[DEBUG] repo returned', { user, type: user === null ? 'null' : typeof user })\n // ...\n}\n\n// Now you know: is `id` the wrong value, or does the repo return unexpected type?\n# Isolate environment issues\nNODE_ENV=production node -e \"require('./dist/main')\" # test prod build locally\n\n# Isolate database issues — run the query directly\npsql $DATABASE_URL -c \"SELECT * FROM users WHERE id = 42;\"\n\n# Isolate network issues\ncurl -v -H \"Authorization: Bearer $TOKEN\" http://localhost:3000/api/v1/users/42\n// BUG: missing await — returns Promise, not value\nasync function getBadge(userId: string) {\n const user = this.repo.findById(userId) // ← missing await\n return user.role === 'admin' ? 'admin' : 'user' // TypeError: user.role undefined\n}\n\n// BUG: forEach with async — fires and forgets\nasync function notifyAll(userIds: string[]) {\n userIds.forEach(async id => { // ← async inside forEach is a trap\n await this.emailService.send(id)\n })\n // returns before any emails sent!\n}\n\n// FIX: use Promise.all or for...of\nasync function notifyAll(userIds: string[]) {\n await Promise.all(userIds.map(id => this.emailService.send(id)))\n // OR (sequential):\n for (const id of userIds) {\n await this.emailService.send(id)\n }\n}\n// BUG: stale closure captures old value\nfunction Timer() {\n const [count, setCount] = useState(0)\n\n useEffect(() => {\n const id = setInterval(() => {\n setCount(count + 1) // ← count is always 0 in this closure\n }, 1000)\n return () => clearInterval(id)\n }, []) // ← empty deps — count never updates in closure\n\n // FIX: use functional update\n useEffect(() => {\n const id = setInterval(() => {\n setCount(c => c + 1) // ← always uses latest value\n }, 1000)\n return () => clearInterval(id)\n }, [])\n}\n// BUG: two concurrent requests overwrite each other\nasync function incrementViews(postId: string) {\n const post = await db.posts.findOne(postId)\n post.views++\n await db.posts.save(post) // request B may have read same value\n}\n\n// FIX: atomic update\nasync function incrementViews(postId: string) {\n await db.posts.increment({ id: postId }, 'views', 1)\n // or: UPDATE posts SET views = views + 1 WHERE id = $1\n}\n// Type assertions hide runtime issues\nconst user = result as User // if result is null, this silently succeeds\nuser.email // CRASHES at runtime\n\n// Safe pattern: validate at runtime\nfunction assertIsUser(value: unknown): asserts value is User {\n if (!value || typeof value !== 'object' || !('email' in value)) {\n throw new Error(`Expected User, got: ${JSON.stringify(value)}`)\n }\n}\n\n// Or use Zod/io-ts at system boundaries\nconst UserSchema = z.object({ id: z.number(), email: z.string().email() })\nconst user = UserSchema.parse(apiResponse) // throws with clear message if wrong\n# Start with inspector\nnode --inspect-brk dist/main.js\n\n# Attach VS Code debugger (launch.json)\n{\n \"type\": \"node\",\n \"request\": \"attach\",\n \"name\": \"Attach to Process\",\n \"processId\": \"${command:PickProcess}\",\n \"sourceMaps\": true,\n \"outFiles\": [\"${workspaceFolder}/dist/**/*.js\"]\n}\n{\n \"version\": \"0.2.0\",\n \"configurations\": [\n {\n \"type\": \"node\",\n \"request\": \"launch\",\n \"name\": \"Debug NestJS\",\n \"program\": \"${workspaceFolder}/src/main.ts\",\n \"preLaunchTask\": \"tsc: build\",\n \"outFiles\": [\"${workspaceFolder}/dist/**/*.js\"],\n \"sourceMaps\": true,\n \"envFile\": \"${workspaceFolder}/.env.local\"\n },\n {\n \"type\": \"node\",\n \"request\": \"launch\",\n \"name\": \"Debug Tests\",\n \"program\": \"${workspaceFolder}/node_modules/vitest/vitest.mjs\",\n \"args\": [\"run\", \"--reporter=verbose\"],\n \"sourceMaps\": true\n }\n ]\n}\n// TypeORM: enable query logging in dev\nTypeOrmModule.forRoot({\n logging: process.env.NODE_ENV === 'development' ? ['query', 'error'] : ['error'],\n})\n\n// Log specific query with explain\nconst result = await this.dataSource.query(`\n EXPLAIN ANALYZE\n SELECT * FROM users WHERE email = $1\n`, ['jane@example.com'])\nconsole.log(result)\n□ Can I reproduce it? (if not, gather more info first)\n□ Did it ever work? (if yes, git bisect to find regression)\n□ What changed recently? (last deploy, config, data migration)\n□ What do the logs say? (search by request ID or user ID)\n□ Is it environment-specific? (only prod? only with certain data?)\n□ What does the stack trace say? (first line, first your-code frame)\n□ What is the actual vs expected value at the crash site?\n□ Is it a type mismatch? null vs undefined? string vs number?\n□ Is it a timing issue? (async, race condition, timeout)\n□ Is it an environment issue? (env vars, secrets, config)\n1. TRIAGE (< 5 min)\n - Identify affected users/scope\n - Is data at risk? → escalate immediately\n - Can we roll back? → do it if yes and impact is high\n\n2. INVESTIGATE (keep timeline)\n - Pull logs: kubectl logs / CloudWatch / Datadog\n - Find first error occurrence: git log + deploy history\n - Identify causal commit or config change\n\n3. MITIGATE\n - Rollback deploy if a commit caused it\n - Feature flag off if available\n - Scale up if load-related\n\n4. FIX\n - Write a failing test that reproduces the bug\n - Fix it\n - Deploy hotfix\n\n5. POSTMORTEM\n - Timeline of events\n - Root cause (not \"human error\" — what systemic issue enabled it?)\n - Action items with owners and due dates\nconsole.log to prod builds — use structured logging