Python Error Handling

Python Error Handling

Standards for raising, catching, and modelling exceptions.

Custom exceptions

• Define domain exceptions in a dedicated exceptions module and raise those rather than

bare ValueError/RuntimeError/Exception, so call sites can catch precisely.

• Subclass Exception, not a built-in like ValueError — inheriting from ValueError

means existing ValueError handlers silently swallow your exception, which is rarely what you want.

• Keep the hierarchy flat — a handful of specific exceptions, optionally sharing one

package-level base class, not deep chains you must trace to know what a catch catches.

• Name each exception for the failure it represents (RequestTimeoutError) and build

its message from the offending values, so the logged event is self-contained.

Catching exceptions

• Catch the narrowest exception type you actually handle. A broad except Exception is

the Any of error handling — it swallows the unexpected and programmer errors (a KeyError, a PermissionError) that should propagate instead.

• A broad except Exception is only correct at a top-level entry point — a

long-running loop or a CLI's main — as a last resort that reports and re-raises (or exits non-zero), so nothing is lost silently.

• Keep try blocks down to the line or two that can actually raise, so it's obvious which

call is guarded.

• Don't catch an exception only to log it and carry on — either handle it (recover) or let

it propagate. And don't log at an intermediate catch when it still bubbles to a handler that logs: log it once, where it's acted on.

Fail fast

• Raise on impossible or coding-error states instead of logging-and-continuing or

returning None. A reached "can't happen" branch is a bug; make it fail loudly.

• Let library failure checks fire: subprocess.run(..., check=True),

response.raise_for_status(), and the like — don't discard return codes or statuses.

• When a 1:1 lookup could return zero or many rows, assert exactly one with

more_itertools.one() rather than silently taking the first.

• Be consistent across sibling functions: a set of lookups should all raise on "not

found" or all return None, never a mix. Prefer raising, so callers can't forget to check.

• Better still, model data so impossible states can't be constructed — see "make invalid

states unrepresentable" in python-code-style.

Log severity

• Calibrate severity to recoverability: reserve critical for unrecoverable failures that

end the process, error/exception for failures needing attention, warning for a recovered or degraded path, info for normal events. Don't log at error for something you handled, nor bury a real failure at warning.

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: owenlamont
• Source: owenlamont/agent_skills
• License: MIT

Install and usage instructions live in the source repository linked above.