Error handling: fail clearly
Things will go wrong: bad input, missing files, a server that doesn't answer. The question is whether your program says so clearly or quietly carries on with wrong data. Silent failures, useful error messages, exceptions vs error values, where to catch, and failing fast, in Python, PHP, Go and JavaScript.
Every program meets things it didn’t expect: a CSV row with 3x in the quantity column, a file that isn’t there, a config value someone forgot to set, an API that times out. You can’t prevent all of them. What you can decide is how your program behaves when they happen.
There are two bad options and one good one. The program can crash with a message nobody understands. It can carry on silently with wrong data. Or it can fail clearly: stop at the right place, say what went wrong and where, and leave things in a sensible state. This part is about the third.
The worst error is the one you don’t see
Here’s the monthly total from part 9, written the “safe” way, so a bad row can’t crash it:
rows = [("book", "2", "85000"), ("pen", "10", "4000"), ("mug", "3x", "35000")]
def total_silent(rows):
total = 0
for product, qty, price in rows:
try:
total += int(qty) * int(price)
except:
pass
return total
print("silent:", total_silent(rows))
silent: 210000
It doesn’t crash. It’s also wrong. The real total, if the mug row had been entered correctly as 3, is 315,000. The mug row vanished, and nothing told anyone. This report might be used to pay a supplier or file taxes. A crash would have been better.
The Zen of Python puts the rule in two lines:
“Errors should never pass silently.” “Unless explicitly silenced.”
Explicitly means you decided, for a reason you could explain, and ideally the program still records what it skipped (as the report in part 9 did with “1 invalid row skipped”). except: pass around a block of code is the opposite of explicit.
A good error message answers three questions
Python’s own error for the bad row is accurate:
ValueError: invalid literal for int() with base 10: '3x'
But it doesn’t say which file, which row, which field. In an import with 40,000 rows, that’s the difference between a five-second fix and an hour of searching. A useful error message answers:
- What went wrong? (“qty must be a whole number”)
- Where? (“line 4”)
- With what value? (“got ‘3x’”)
Add that context where you have it, and keep the original error attached. In Python, raise ... from does this; the tutorial says the from clause is used “To indicate that an exception is a direct consequence of another” and that “This can be useful when you are transforming exceptions.”
class InvalidRow(Exception):
pass
def parse_row(line_no, row):
product, qty, price = row
try:
return product, int(qty), int(price)
except ValueError as e:
raise InvalidRow(
f"line {line_no}: qty/price must be whole numbers, got qty={qty!r} price={price!r}"
) from e
Traceback (most recent call last):
File ".../loud.py", line 7, in parse_row
return product, int(qty), int(price)
ValueError: invalid literal for int() with base 10: '3x'
The above exception was the direct cause of the following exception:
Traceback (most recent call last):
...
InvalidRow: line 4: qty/price must be whole numbers, got qty='3x' price='35000'
Both errors are there: the low-level cause and the message a person can act on. (Line 4 because the header is line 1.)
Notice also except ValueError, not except:. The Python tutorial’s advice: “it is good practice to be as specific as possible with the types of exceptions that we intend to handle, and to allow any unexpected exceptions to propagate on.” Catch what you expect and know how to handle. Let the rest go up.
Two styles: exceptions and error values
Languages handle errors in two main ways.
Exceptions (Python, PHP, JavaScript, Java, C#): an error jumps out of the current function and up the call stack until something catches it. Code in between doesn’t have to mention it. That keeps the normal path clean, but it means any call might throw, and you can’t see that from the call site.
Error values (Go, and Rust in its own way): an error is just a returned value, and the caller has to look at it. The Go blog’s summary is three words, “Errors are values”, and the consequence: “Values can be programmed, and since errors are values, errors can be programmed.”
var ErrInvalidRow = errors.New("invalid row")
func parseQty(line int, raw string) (int, error) {
qty, err := strconv.Atoi(raw)
if err != nil {
return 0, fmt.Errorf("line %d: %w: %w", line, ErrInvalidRow, err)
}
return qty, nil
}
line 4: invalid row: strconv.Atoi: parsing "3x": invalid syntax
true
The %w verb wraps the original errors inside the new one, and “Wrapping an error with %w makes it available to errors.Is and errors.As”. So the caller can still ask errors.Is(err, ErrInvalidRow) and get true, the second line above. The same works for the standard library’s errors: reading a missing file gives open orders.csv: no such file or directory, and errors.Is(err, os.ErrNotExist) is true.
Neither style is better everywhere. The goal is the same in both: don’t lose the error, and don’t lose its context.
JavaScript has the same “wrap and keep the cause” idea. MDN: the cause property “indicates the specific original cause of the error” and is used “when catching and re-throwing an error with a more-specific or useful error message”:
function parseConfig(text) {
try {
return JSON.parse(text);
} catch (err) {
throw new Error("config.json is not valid JSON", { cause: err });
}
}
config.json is not valid JSON
cause: SyntaxError: Expected double-quoted property name in JSON at position 14 (line 1 column 15)
PHP: watch for quiet conversions
PHP deserves a special note, because some of its conversions fail quietly:
var_dump((int) "3x"); // int(3)
var_dump((int) "abc"); // int(0)
A cast never complains. "3x" becomes 3, and "abc" becomes 0. A missing array key only produces a warning and then null, which turns into 0 in arithmetic:
PHP Warning: Undefined array key "qty" in Command line code on line 1
int(0)
If warnings aren’t watched, that’s a silent wrong total again. PHP 8 is stricter in places ("abc" * 2 now throws TypeError: Unsupported operand types: string * int), but for input you should validate explicitly and throw when it’s wrong:
function parseQty(string $raw): int {
$qty = filter_var($raw, FILTER_VALIDATE_INT);
if ($qty === false) {
throw new InvalidArgumentException("qty must be a whole number, got '$raw'");
}
return $qty;
}
// parseQty("3x") → InvalidArgumentException: qty must be a whole number, got '3x'
Fail fast
“a fail-fast system is one that immediately reports at its interface any condition that is likely to indicate a failure.” Such systems are “designed to stop normal operation rather than attempt to continue a possibly flawed process.”
In practice: check things as early as you can, at the edge where data comes in. A missing setting should stop the program at startup, not when the first customer tries to reset a password three days later:
REQUIRED = ("DATABASE_URL", "SMTP_HOST")
def load_settings(env):
missing = [key for key in REQUIRED if not env.get(key)]
if missing:
raise SystemExit(f"Cannot start: missing settings {', '.join(missing)}")
return {key: env[key] for key in REQUIRED}
Cannot start: missing settings SMTP_HOST
exit code: 1
The same goes for user input, CSV rows, and API responses: validate them when they arrive, and turn them into clean values (part 9’s parse_order did exactly this). The rest of the code can then trust what it receives.
Where to catch
A useful rule of thumb: raise low, catch high.
- Low-level code (parsing a row, reading a file) usually doesn’t know what to do about an error. Should a bad row stop the whole import? Be skipped? Be reported? It depends on the caller. So it raises, with context.
- High-level code (the request handler, the command, the job) knows the situation. That’s where you decide: show the user a message, log the details, skip and count, retry, or stop.
And at the very top, have one place that catches anything unexpected, logs the full details for you, and shows the user something short and safe. Users should see “We couldn’t import line 4: quantity must be a whole number”, not a stack trace with file paths and SQL. Showing internals is also a security problem, which part 22 comes back to.
Clean up, even when things fail
When something fails halfway, files may be open, a transaction half-written, a lock held. Python’s finally “will execute as the last task before the try statement completes”, and it “runs whether or not the try statement produces an exception”:
def import_file(path):
print("open", path)
try:
raise InvalidRow("line 4: ...")
finally:
print("close", path)
open orders.csv
close orders.csv
report to user: line 4: ...
Most languages have a tidier form for the common cases: with open(...) in Python, defer f.Close() in Go, finally in PHP and JavaScript, and database transactions that roll back if something fails. Use them, so an error doesn’t leave a mess behind it.
Expected and unexpected errors
It helps to separate two kinds:
- Expected failures are part of normal life: invalid input, a file that doesn’t exist, a payment declined, a network timeout. Handle them on purpose, with clear messages, and sometimes a retry.
- Bugs are things that should never happen: a
Nonewhere there’s always supposed to be a value, an index past the end of a list. Don’t hide them. Let them fail loudly, log them, and fix the code.
Python’s glossary describes the common Python style, EAFP (“Easier to ask for forgiveness than permission”), which “assumes the existence of valid keys or attributes and catches exceptions if the assumption proves false.” That works well for expected failures. It’s not a license to wrap bugs in try until they go quiet.
Why this matters day to day
- Wrong data is worse than no data. A crash gets noticed and fixed. A silently wrong report gets trusted.
- Support time. “Line 4: quantity must be a whole number, got ‘3x’” lets a user fix their own file. “Something went wrong” becomes a ticket.
- Debugging. An error with context and a kept cause usually points straight at the problem. Part 15 builds on this.
- AI-generated code often wraps things in broad
try/exceptorcatch (e) {}to make it “robust”. Check what’s being caught, and what happens to the error.
Try it yourself
- Search your code for
except:,except Exception: pass,catch (e) {}or@in PHP. For each one, decide: should this be specific, logged, or removed? - Take an error message from a project you work on and rewrite it to answer what, where, and with what value.
- Make a script check its required settings at startup and exit with a clear message if one is missing.
- In PHP, compare
(int) "12abc",intval("12abc"), andfilter_var("12abc", FILTER_VALIDATE_INT). Which one would you use for user input?
Summary
- Fail clearly: stop at the right place, say what went wrong, and leave things clean.
- Silent failures are the worst kind: “Errors should never pass silently. Unless explicitly silenced.”
- Good error messages say what, where, and with what value, and keep the original cause (
raise ... from,%w,{ cause }). - Catch specific errors, let unexpected ones propagate; raise low, catch high.
- Fail fast: validate settings and input at the edge.
- Use
finally,with,defer, and transactions so failures don’t leave a mess. - Handle expected failures on purpose; let bugs be loud.
References
- Errors and Exceptions, Python tutorial; PEP 20 – The Zen of Python; Glossary: EAFP.
- Errors are values and Working with Errors in Go 1.13, The Go Blog.
- Error: cause, MDN Web Docs.
- Exceptions and filter_var, PHP manual.
- Fail-fast system, Wikipedia.