Lesson 13.813.8 When it breaks: reading an error

In everyday life. When a car's dashboard light comes on, "the car is broken" does not help the mechanic. "The oil light came on at highway speed, and the engine was hot" does.

What you will learn. How to read what a program prints when it fails, and name the cause in one sentence.

Why it matters. When a program breaks, it tells you what went wrong and where. Read it, and tell the agent exactly what broke.

When a program fails, it prints an error report: a stack trace in TypeScript under Node, a traceback in Python. Both say what kind of error it was, its message, and the chain of function calls that led to the line. A function calls another when it uses it.

Where do I start reading an error?

At the bottom for Python, and at the top for Node. Python tells it like a story, with the ending last: the oldest call comes first, and the failing line and then the message come last. Node tells it like a news report, with the headline first: the message near the top, then the failing line, then the lines that called it.

In both, skip the lines that point into the language itself, such as node:internal and <frozen runpy>. Then, starting from the message, find the first line in a file you own.

Why is the failing line not always the bug?

A program raises an error, stopping to report it, at the line where a bad value finally causes trouble. The bug is often earlier, where the bad value came from. It is like a payment the bank sends back: the mistake was made earlier, when someone typed the vendor's account number. Follow the chain back to the first place in your own code that passed it along.

At work. Ana has the agent run the reconciliation script, which checks each stated due date against the terms, on a file with no terms column. Both languages fail.

Predict: which line in your own code did the bad value come from?

$ npm run reconcile -- data/invoices-no-terms.csv
file:///.../src/due-date.ts:13
    throw new Error(`Unknown terms: ${terms}`);
          ^

Error: Unknown terms: undefined
    at termsDays (file:///.../src/due-date.ts:13:11)
    at dueDate (file:///.../src/due-date.ts:22:39)
    at reconcile (file:///.../src/reconcile.ts:16:22)
    at file:///.../src/reconcile.ts:26:17
    at ModuleJob.run (node:internal/modules/esm/module_job:439:25)

In the Node report, the first lines are in due-date.ts, which raised the error on purpose, with throw. The bug is one step further down, at reconcile.ts:16, which passed undefined. In the Python report, the message is at the bottom, and just above it Python marks the exact expression, row["terms"].

Ana's sentence. "The error is raised in due-date.ts, but the cause is reconcile.ts line 16: this file has no terms column, so the terms it passes are undefined." In Python, her sentence would name reconcile.py line 21, which asks for a column the file does not have. Then she asks: "Please make the script stop with a clear message that names the missing column. Don't fill in default terms."

"It broke" is not enough. The most expensive habit is saying "it failed, fix it" without reading the error. Like a mechanic asked only to turn the oil light off, the agent may hide the error instead of fixing its cause, for example by giving every row with no terms "Net 30".

Where the languages differ. A missing key in TypeScript gives undefined, which is passed along until something else fails, so the error appears far from the cause. Python raises KeyError at the lookup itself.

Try it

The file in 13-8 is the while loop from 13.4. It works. You are going to break it.

Modify. Send: "Please remove the empty page, the last [], from the list of pages in the file. Don't run it yet." Predict what happens now.

Run. Send: "Please run the file and show me the whole error. Don't explain it yet."

Investigate. Read the report from where this lesson says to start. Write one sentence that names the file, the line and the cause. Then ask the agent what it thinks, and compare.

Make. Send: "Please change the loop so it also stops at the end of the list, even with no empty page. Run it."

What you should see. Two pages print, then a TypeError in TypeScript or an IndexError in Python, on the while line. The cause is the data you changed. After the fix, it stops at page 3 with no error.

The operating rule: read the error before you ask for a fix, find the first line in your own code, follow the bad value back, and name the file, the line and the cause in one sentence.

Figure 13.9. Reading an error report. In Python start at the bottom, in Node start at the top, and in both find the first line in a file you own, then follow the bad value back.

Next. An error tells you what went wrong. 13.9 writes down what right looks like, before any code exists.