What does BaseException.add_note() do to an exception object in Python?

`add_note` is a method on `BaseException` itself, which means **every** exception object in Python carries it: a `ValueError`, your own subclass, `KeyboardInterrupt`, an `ExceptionGroup`. It arrived in Python 3.11 with PEP 678 and is unchanged through 3.14. Its entire job is to attach an extra line of human-readable context to an exception *instance that already exists*, without constructing a new exception and without altering the one in hand. ## What the call actually does `exc.add_note("record_id=8842")` looks for a list attribute named `__notes__` on the instance; if there is none it creates one, then appends the string. Two consequences fall straight out of that implementation: * **The attribute is absent until the first call.** `ValueError("x").__notes__` raises `AttributeError`. Any code that inspects notes generically must use `getattr(exc, "__notes__", [])`, and that is the single most common bug when people first automate around this feature. * **Notes accumulate, they do not replace.** A second call appends, and the list preserves call order. That is what makes a trail of notes readable as a path from the innermost layer outward: the first line is where the failure happened, the last is the outermost frame that decorated it. Because `__notes__` is an ordinary list on an ordinary object, you can also read it, filter it, or replace it wholesale. There is no hidden machinery. ## What it deliberately does not touch The exception's class is the same, so every `except` clause downstream behaves identically. `args` is the same, so anything constructing a message from `exc.args` is unaffected. `str(exc)` is the same, which matters more than it sounds: a log line written as `logger.error("failed: %s", exc)` prints only the message and silently drops every note, while anything that formats the **full traceback** includes them. The traceback object and any chaining links are untouched as well. That separation is the design: a note is metadata for a human reading a failure, not data for a program. If some caller must branch on the context you are adding, a note is the wrong carrier — set an attribute on the exception instead. If a human debugging a production traceback needs to know which record, which shard, which config file, a note is exactly right. ## The argument is a string, always Passing anything else raises `TypeError: add_note() argument must be str, not bytes`. Format the value yourself: ```python exc.add_note(f"record_id={record_id}") ``` There is no implicit `str()` conversion and no multi-argument form; call `add_note` once per line you want. ## How notes render Every renderer in the standard library goes through the same formatting code, so notes show up consistently: the default interpreter handler on an uncaught exception, `traceback.print_exception`, `traceback.format_exception`, `traceback.format_exc`, and `logging.Logger.exception`. The shape is: ``` Traceback (most recent call last): ...frames... ValueError: score out of range record_id=8842 scorer=v3 ``` Each note occupies its own line, unindented, directly below the `Type: message` line and in insertion order. `traceback.TracebackException` captures the notes too, so an exception summarised now and formatted later — or serialised and rendered elsewhere — keeps them. If someone has assigned a non-list to `__notes__`, the formatter does not crash; it falls back to printing that object's repr. ## Why the feature exists Before 3.11 there were three ways to add context to an error travelling up a stack, and each cost something. Build a new exception with a richer message: now callers must catch a different type, and readers must follow a chain. Mutate `args`: fragile, and downstream code may depend on its shape. Log at every layer: one failure becomes several log lines that only help if your log pipeline reassembles them. `add_note` is a fourth option that preserves identity — the same object, the same type, the same traceback, plus a line of context. ## Typical shape The two common patterns are annotating an exception you are about to raise, and annotating one you caught. The first looks like: ```python err = ValueError("score out of range") err.add_note("record_id=8842") raise err ``` You need an instance to call the method on, so this splits the usual one-line `raise ValueError(...)`. The second — catch, annotate, re-raise the same object — is the pattern most interviews are really probing, and it is what makes notes accumulate across layers. ## Content guidance Keep notes short, greppable and key=value shaped: identifiers, stage names, versions, the config path that was loaded. Never put credentials, tokens, personal data or a large payload in one, because a note is reproduced verbatim everywhere the traceback goes — crash reports, aggregators, tickets pasted into chat.