Handling Exception Context

Python
# Implicit chaining (__context__): happens automatically when an exception
# is raised inside an except/finally/with block.
try:
    1 / 0
except ZeroDivisionError:
    raise RuntimeError("computation failed")
# Traceback shows both exceptions, joined by:
# "During handling of the above exception, another exception occurred."

# Explicit chaining (__cause__): use `raise ... from ...` to state the cause
# deliberately, e.g. when translating a low-level error into a domain error.
try:
    connect()
except ConnectionError as e:
    raise ServiceUnavailable("cannot reach backend") from e
# Traceback says: "The above exception was the direct cause of the
# following exception."

# Suppress chaining entirely with `from None`.
try:
    parse(data)
except ValueError:
    raise ValueError("bad input") from None

Progress checklist for reasoning about or writing chained-exception code:

• Identify whether the new exception is raised while handling another (implicit context) or is caused by another (explicit cause you want documented)
• Decide if the original exception is genuinely relevant to the caller — if not, suppress it
• Choose the right mechanism: implicit (__context__), explicit (raise X from Y, sets __cause__ and implies __suppress_context__ = True), or suppressed (raise X from None)
• Verify traceback output matches intent (correct linking message, or no extra context)
• For libraries: prefer explicit from e when translating exceptions across abstraction boundaries so users can inspect the root cause via e.__cause__

Example 1 — Implicit context (accidental double failure): Input:

Python
try:
    open("missing.txt")
except FileNotFoundError:
    log.write("error")  # log is undefined -> NameError

Output: Traceback shows FileNotFoundError first, then "During handling of the above exception, another exception occurred:", then NameError. Both are genuinely useful for debugging, so leave as-is.

Example 2 — Explicit cause (intentional translation): Input:

Python
try:
    json.loads(payload)
except json.JSONDecodeError as e:
    raise ConfigError("invalid config file") from e

Output: Traceback shows the original JSONDecodeError, then "The above exception was the direct cause of the following exception:", then ConfigError. config_error.__cause__ is the JSONDecodeError instance.

Example 3 — Suppressed context (irrelevant internal detail): Input:

Python
try:
    cache[key]
except KeyError:
    raise LookupError(f"{key} not found") from None

Output: Traceback shows only LookupError; the internal KeyError is hidden because it's an implementation detail irrelevant to the caller.