How to Read an Error

1. Red error text is a map

At the portal, Tommy runs into a live red error. Not a line from the overnight log, but that very red wall of text that appears on the screen right now when something crashes. Unfamiliar words, file paths, nothing human. His first instinct is still the same: close it and pretend he never saw it, or better yet, send it to someone smarter. Like Alex.

“Stop.” Alex catches that urge. “Where are you closing it? You are throwing away evidence right now.”

“What evidence? It’s just an error. A mess of red text.”

“It’s not a mess. It’s a crime scene map.” Alex won’t let him run. “In this ‘wall of text,’ it is definitely recorded where and what broke. Closing it is like closing your eyes at the scene of an accident so you don’t have to look. Learn to read it, and fear turns into evidence. Let’s break it down; it’s simpler than it looks.”

And for the first time Tommy doesn’t close the red text, but reads it carefully — as if he is translating it into human language. Not a magical curse, but a foreign language you can parse.

2. Stack trace: type, file, line

“This wall of text is called a stack trace,” Alex says. “In English, stack trace, ‘a trace of the call stack.’ Sounds scary, but it contains only three useful things. Look, I’ll cut out the extra stuff and show you the skeleton.”

Here’s what it looks like in full, unprocessed — exactly what Tommy sees in the terminal:

Above the stack trace there’s a bonus: the file, the line and the line of code itself, and the ^ marker shows exactly where it tripped. And that whole tail of node:internal lines is Node’s own internals — your code isn’t there, so feel free to skip it. Read from the top and look at the lines with your own files — skip the others. Your files and lines will be different, but it works the same way.

He points to a trimmed example on the screen (comments are explanations; they are not in the real log):

TypeError: Cannot read properties of undefined (reading 'score')   # ERROR TYPE — what went wrong
    at calculateReward (reward-flow.js:30)              # FILE and LINE — where it broke
    at processClaim (portal.js:23)                      # who called it (chain)

“See the three pieces?” Alex breaks it down on his fingers. “The first line is the type of error: what exactly went wrong. The second is the file and line: where it happened, reward-flow.js, line 30. The third and below — who called it, the call chain: from bottom to top, who called whom. That’s all. A stack trace is a direct pointer: go to this file, to this line, and look at what is happening there.”

How to read a stack trace. Example: TypeError: Cannot read properties of undefined (reading 'score'), at calculateReward (reward-flow.js:30), at processClaim (portal.js:23). The first line is the error type, what went wrong: an empty value undefined came in, and the code tried to read score from it. The at line right below is the file and line where it crashed: open reward-flow.js at line 30. The lines below are the call chain, who called it: processClaim from portal.js called calculateReward; below is the caller, above is the one called. The top at line is where it crashed, below is the path that led there. A stack trace is a pointer: what broke, where, and how the program got there. How to read a stack trace TypeError: Cannot read properties of undefined (reading 'score') at calculateReward (reward-flow.js:30) at processClaim (portal.js:23) Error type what went wrong an empty value came in undefined, and the code tried to read score File and line where it crashed open reward-flow.js at line 30 and look at what came in there Call chain who called it processClaim from portal.js called calculateReward below — the caller, above — the callee The top at line — where it crashed. Lines below — the path the program took to get there A stack trace is a pointer: what broke, where, and how the program got there

Tommy peers closer. And instead of “everything blew up, it’s over,” for the first time he gets a normal shape of thought:

“So it’s not ‘everything exploded.’ It’s ‘it exploded right here, in this file, on this line.’”

“Exactly. It’s a navigator to the place of failure, not a reason to close the terminal. Like an airplane’s black box: the tape is scary, but it records exactly where and at what moment something failed. You don’t throw away the black box — you decode it.”

3. Where it blew up != where the mine was planted

Tommy is already eager to jump in:

“Great, got it! Line 30, file reward-flow.js. I go there, fix that line — and that’s it?”

“Hold on.” Alex restrains him. “The most common beginner mistake. The place where it blew up is not always the place where the mine was planted.”

“What do you mean? It literally shows line 30.”

“It shows where it dropped. That’s a symptom. And the cause — the root — can be sitting somewhere completely different. Look: the program crashed on line 30 because an empty value came in there. But it didn’t come empty from here — somebody made it empty three steps earlier, in a different file. Fix line 30 — you’ll silence the symptom, but the root will remain, and it will resurface somewhere else a little later.”

Alex finds an image:

“It’s like smoke in an airplane cabin. You see the smoke in the cabin — that’s where it hurts. But what’s actually burning is wiring under the floor. Trying to put out the smoke in the cabin is pointless: until you fix the wiring, it will keep coming back. Symptom — smoke. Root — wiring.”

Where it crashed is not always where it was broken. A value travels along the call chain: data comes in, for example a user's request; then the value gets broken, for example a check was removed and the empty value went through — this is the root; then it is passed on, and nothing crashes yet; and finally it crashes here — this is the symptom, and this is exactly the place the stack trace shows. If you fix the crash site, the symptom is plugged, the root stays, and it crashes again a bit to the side. If you go back along the chain, you find where the value was broken and fix the cause — it takes longer, but you fix it once. The stack trace line is where it crashed. Look for where the broken value came from. Where it crashed isn't always where it broke The value travels along the call chain Data came in for example, a user's request ROOT Here the value got broken e.g. a check was removed — the empty value went on Passed on nothing crashes yet SYMPTOM It crashed here this is the place shown by the stack trace Fixing the crash site symptom plugged, root stays crashes again, a bit to the side fast — and it feels fixed Going back along the chain find where the value got broken fix the cause takes longer, but you fix it once The stack trace line is where it crashed Look for where the broken value came from

Tommy nods slowly.

“So,” he says, “before, for me this was a black box. It broke — kick it or send it to someone smarter; there were no other options. But here, it turns out, there are facts inside. And with those facts I can handle it myself.”

“Yourself,” Alex replies. “Not kick it, but read it.”

4. Two clues: stack trace and log

“Listen, and that overnight log I read this morning — how does it fit in here?” Tommy remembers. “It’s about that same night too.”

“Very much so.” Alex perks up. “That’s your second clue, and it’s of a completely different nature. Look at the difference. The stack trace is the accident site right now: it’s smoking here, this file, this line. And the overnight log is the chronicle of events: what the agent decided to do at night and in what order. Where it disabled tests, where it tore down a page, where it forced the result, where it left no way back.”

“So one says ‘where it hurts,’ and the other says ‘what was happening’?”

“Exactly. A stack trace is like tracks in the snow where something fell. A log is like a security camera recording of who wandered around this yard all night. The stack trace answers ‘where,’ the log answers ‘what was changed nearby and why.’ And here’s the most important part: each one on its own is half-blind. The stack trace will show the place of the explosion, but it won’t say who planted it. The log will show that the agent was poking at reward-flow at night, but on its own it does not prove that this is what caused the explosion.”

5. Combining two clues: facts first, agent second

“Then how do you turn two half-blind clues into one that can see?” Tommy asks.

“By combining the two clues.” Alex clearly expected the question. “And you happen to have exactly two. The first is the stack trace on the screen: it tells you where it blew up now. The second is the overnight log: it tells you what the agent changed at night in this area. Separately, each one is half-blind. Together, they form a stereoscopic picture.”

“So I look at where it fell, and then I scan the log — what did the agent touch near this place?”

“Exactly. The stack trace showed you reward-flow.js, and one line below — who called it: portal.js. You go into the overnight log and look for what the agent did to those files at night. You find 04:08: ‘simplified’ the input validation in portal.js. The empty value came from there — and there it is, the root. Not where it smoked, but where he planted the mine at night. Match one with the other — and you find the real cause, not just the place of the explosion.”

And here Tommy lays out the sequence himself, as if he is quietly repeating a new rule to himself:

“So it goes like this: first I look at the facts myself — stack trace plus log. And only then do I call the agent to fix it. Not the other way around.”

“Now you sound like an engineer,” Alex replies. “Because if you call the agent without facts on input — with just ‘it doesn’t work, fix it’ — it will start guessing. And a guessing agent was precisely the source of all the trouble that night. Facts first. Agent second.”

Two clues: where it crashed and what was changed. The stack trace tells you where it crashed right now: the file and line, the call chain; but it won't tell you who broke it or when. The agent's log tells you what the agent changed and in what order: which files it touched, what it decided and when; but it won't prove that this is why it crashed. Each clue on its own is half-blind. Together they give the probable cause: the crash site plus what the agent changed near it. The order: first the facts — the stack trace and the log, then you find the probable cause, and only now the agent — with an exact clue. Without facts: "it doesn't work for me, fix it" — the agent guesses, like that night. Facts first. Then the agent. Two clues: where it crashed and what was changed Stack trace where it crashed right now file and line call chain won't tell you who broke it or when Agent's log what the agent changed and in what order which files it touched what it decided and when won't prove that this is why it crashed + each clue on its own is half-blind Together — the probable cause crash site + what the agent changed near it Order First facts: stack trace and log Then find the probable cause Only now the agent — with an exact clue No facts: "it doesn't work for me, fix it" the agent guesses — like that night Facts first. Then the agent