Skip to content
Tutorials Center
My learning

Topics

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.

Python
try:
    int("abc")
except ValueError as error:
    raise RuntimeError("could not read the setting") from error

Try it

Python Implicit context and explicit cause

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.

Python raise from None and walking the chain

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__ from raise ... 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 error whenever you wrap a lower-level exception in a domain-specific one. Callers catch the new type, and developers still see the original.
  • Use from None only 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__ becomes True.
  • raise alone 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 or None also works: raise X from Y requires Y to be an exception instance, an exception class or None, otherwise TypeError.
  • Context is automatic and recursive. Every raise inside an except or finally block links to the exception being handled, which can build long chains; Python avoids cycles for you.
  • Handlers that fail. If code in except or finally raises 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.