DBG-09 · SEC. 02 Debugging & Evaluation

Error Message Forensics Loop

Force the AI to parse the exact error text and stack trace before it's allowed to guess a cause.

FORMAT: loop
DIFFICULTY: intermediate
TIME: 10 min
TOOLS: claude-code · cursor · codex-cli · gemini-cli
MODELS: any
COPIES: 0 so far

When to use this

You have a real error message or stack trace in hand and the AI's first move is "this is probably a [library] issue" before it has read a single line of the trace. You want the trace read literally, not pattern-matched against a generic cause.

The pattern

Pastes as plain text

Work from the exact error output, not from what this error type
usually means.

Before proposing any cause, do this in order and show your work at each step:

1. Quote the smallest relevant error message text back to me, redacting any
   secrets, tokens, personal data, or customer content. Do not paraphrase
   the technical parts that identify the failure.
2. List every file:line reference in the stack trace, in the order the
   trace gives them, from where the error was thrown down to where it
   originated in application code. Skip frames only if the trace itself
   marks them as library/framework internals.
3. Open and read each of those file:line locations, starting from the
   deepest application-code frame. Quote the relevant code at that exact
   line, redacting secrets or customer data rather than copying them.
4. State what the error literally means at that specific line: trace the
   variable, argument, or condition that has to be undefined, wrong-typed,
   or false for this exact error to fire there. Do not describe what this
   error type "usually means" in general.
5. Only after step 4, state the root cause as one sentence tied to the
   specific line and value you just traced.

If a frame has no resolvable file:line, say so explicitly instead of
guessing which file it might be. Do not name a library, framework, or
"common cause" for this error type until steps 1-4 are complete on the
actual trace.

First, ask me to paste a redacted error / stack trace, then wait. If I give a
file path or a command instead, read or run it yourself and report only the
relevant redacted output.

Real example output

Step 1: "TypeError: Cannot read properties of undefined (reading 'id')"

Step 2: Frames in application code: `getUserOrders (src/services/orders.ts:34:19)`, called from `OrdersPage (src/pages/orders.tsx:19:26)`.

Step 3: `orders.ts:34` reads `const orderId = session.user.id;`. `orders.tsx:19` calls `getUserOrders(session)` inside `useEffect`, before the auth provider's `session` has resolved from `undefined` to the real object.

Step 4: On the first render, `session` is `undefined` by design (the auth hook initializes it that way until the token check resolves), so `session.user` throws before `.id` is ever reached. This isn't a library bug, it's a call made one render too early.

Step 5: Root cause: `OrdersPage` calls `getUserOrders(session)` before checking `session` is loaded, so `session.user.id` runs against `undefined`.

Fix: added `if (!session) return null;` guard in `orders.tsx:18`, before the `getUserOrders` call. Re-ran the page, error gone, orders load once session resolves.

Why it works

Reading the trace top to bottom and quoting real code at each frame stops the model from recognizing the error type ("Cannot read properties of undefined") and reaching for the first library-shaped explanation it's seen before. Tying the cause to one specific line and value keeps the fix targeted instead of defensive code sprayed everywhere.

Related patterns

DBG-01Root Cause Debugging LoopForce one hypothesis at a time against real evidence, so the AI stops guess-and-check fixing.DBG-12Log Diff Divergence LoopCompare logs from a working run and a broken run side by side to find where behavior splits.DBG-16Silent Failure HuntScan a codebase area for swallowed errors and ignored rejections that hide real bugs.