Runtime Error Explainer

Turn a stack trace into a one-line answer: what broke, where, and why.

Read the stack in the right order

Rule: Find the first stack frame in code the user controls. That's where they look first, regardless of what the error message says.

Errors that lie about where the problem is

The message points at line X. The bug is somewhere else. Catalog:

Chained/wrapped exceptions

Caused by: (Java), The above exception was the direct cause of (Python), InnerException (.NET). The innermost cause is the real error. Everything above it is packaging.

Unwrap until you hit the bottom. Explain that.

Translation templates

• NPE/AttributeError: "<var> is null at <file>:<line>. It was supposed to be set by <earlier-line>, which <didn't run | returned null | ran with wrong args>."
• KeyError/missing attribute: "<key> isn't in <object> at <file>:<line>. <object> was built at <earlier-line> — <key is conditional and the condition was false | key name is misspelled | the shape changed upstream>."
• Type error: "<fn> at <file>:<line> expected <type> but got <actual>. <actual> came from <source> — <the API changed | a transform is missing | wrong variable passed>."
• Timeout/Connection refused: "This isn't a code bug. <service> at <host>:<port> is <not running | unreachable | slow>. Verify: <concrete check command>."

Worked example

Input:

Traceback (most recent call last):
  File "/app/api/handlers.py", line 89, in get_order
    return serialize(order, user.preferences.currency)
  File "/app/models/user.py", line 34, in __getattr__
    return self._data[name]
KeyError: 'preferences'

Analysis: Python → bottom-up → error is KeyError: 'preferences'. First user-controlled frame is handlers.py:89, which accesses user.preferences. The __getattr__ frame is a dynamic attribute proxy — it reports what was missing but not why.

Explanation:

user has no preferences attribute at handlers.py:89.

user here comes from whatever loaded it — likely a User.load() call earlier in get_order. The preferences field was never populated. Three common reasons: (a) the user row in the DB has no preferences set and the model doesn't default it; (b) the ORM query is doing a partial SELECT that skips the column; (c) preferences was recently renamed/moved.

First check: print(user._data.keys()) right before line 89.

Edge cases

• No stack trace, just an exit code: exit 137 → OOM-killed; exit 139 → SIGSEGV. Look at system logs, not the app.
• Stack trace is all library frames: The user's code is the thing that called into the library. Find the boundary.
• Async/event-loop traces: The stack is shallow and unhelpful because the real caller is on the other side of an await. Look for "task was created at" / asyncio origin tracking.
• Minified JS / stripped binary: Stack frame names are garbage. Ask for source maps / debug symbols before continuing.

Do not

• Do not paraphrase the error message. "You got a NullPointerException" is not an explanation.
• Do not explain what a NullPointerException is. Explain why this one happened.
• Do not suggest wrapping the line in try/except as a fix. That's a symptom suppressor.
• Do not stop at the crash line when the table above says the bug is upstream.

Output format

## What broke
<one sentence — the real error, unwrapped>

## Where to look
<file>:<line>  — <why this frame, not the one the error points at>

## Likely cause
<ranked list, 1–3 items, most likely first>

## Verify with
<one concrete diagnostic step — a print, a breakpoint, a query>