Python Reference ยท Exceptions
Exception chaining in Python
Explains Python exception chaining: implicit __context__, explicit raise ... from, raise from None, __cause__, __suppress_context__ and reading chained tracebacks.
When one exception happens while another is being handled, Python links them, so the final traceback tells the whole story. There are two links. __context__ is set automatically to the exception that was being handled. __cause__ is set when you write raise NewError from original, to say that the original error directly caused the new one.
Chaining lets you translate low-level errors into meaningful ones (a KeyError into a ConfigError) without losing the original details. This page explains the three forms and how to read what Python prints.
try: int("abc") except ValueError as error: raise RuntimeError("could not read the setting") from error
Try it
Press Run (or Ctrl + Enter) to see the result here.
Program input ยท what you'd type while the program runs
Type the answers before you press Run, one per line. Each time the program reads a line (with input()), it gets the next line from this box.
Press Run (or Ctrl + Enter) to see the result here.
Program input ยท what you'd type while the program runs
Type the answers before you press Run, one per line. Each time the program reads a line (with input()), it gets the next line from this box.
Reading chained tracebacks
Python prints the chain from the oldest exception to the newest, separated by a sentence:
During handling of the above exception, another exception occurred:marks an implicit__context__. This often means a bug in your error handling, or a second failure while cleaning up.The above exception was the direct cause of the following exception:marks an explicit__cause__fromraise ... from. The translation was deliberate.
Read the last exception first (it is what escaped), then look above it for the original problem. The first traceback is usually the root cause.
Choosing the form
| Form | __cause__ |
__context__ |
Printed |
|---|---|---|---|
raise New inside except |
None |
the handled exception | Both, "during handling" |
raise New from original |
original |
the handled exception | Both, "direct cause" |
raise New from None |
None |
the handled exception (kept) | Only New |
raise New outside any handler |
None |
None |
Only New |
Usage notes
- Use
from errorwhenever you wrap a lower-level exception in a domain-specific one. Callers catch the new type, and developers still see the original. - Use
from Noneonly when the original is noise or would leak private details (such as a path or a password in a message). The context is kept in__context__but hidden from the display, since__suppress_context__becomesTrue. raisealone re-raises the current exception unchanged and keeps its traceback. It is the right choice when you only want to log and pass the error on.- Setting
__cause__to any exception orNonealso works:raise X from YrequiresYto be an exception instance, an exception class orNone, otherwiseTypeError. - Context is automatic and recursive. Every
raiseinside anexceptorfinallyblock links to the exception being handled, which can build long chains; Python avoids cycles for you. - Handlers that fail. If code in
exceptorfinallyraises by accident (a typo, a missing attribute), the new error carries the original in__context__, which makes such bugs easy to spot. - Notes, not chains, are for adding information to an exception without a new type:
error.add_note("while reading config.toml")(3.11+) shows up under the message. - Exception groups wrap several exceptions at once; they are separate from chaining, and each member keeps its own cause and context.
traceback.format_exception(error)(accepting just the exception since 3.10) returns the full chained text for logging.