What is Python's ExceptionGroup, and what raises one in the standard library?

### One failure won, and the rest were lost Python propagates exactly one exception object at a time. That is fine for sequential code, where the first failure ends the operation, but it breaks down as soon as one logical operation fans out into many independent ones: a set of concurrent tasks, a batch of files, a fan-out to several backends. Before Python 3.11 the choices were to raise the first failure and discard the others, to invent a private container class that no caller recognised, or to log the extras and hope somebody read the log. PEP 654, shipped in **Python 3.11**, added two builtin exception types that carry several exceptions at once, plus the `except*` syntax for handling them. ### The two builtins `BaseExceptionGroup` derives from `BaseException` and can hold any exception. `ExceptionGroup` derives from both `BaseExceptionGroup` and `Exception`, and may only hold instances of `Exception`. Both are constructed the same way: ```python eg = ExceptionGroup('extraction failed', [ValueError('bad timestamp'), OSError('no track')]) ``` The first argument is a message, exposed as `.message`. The second is a non-empty sequence of *already-instantiated* exceptions, exposed as the tuple `.exceptions`. Each contained exception keeps its own `__traceback__`, `__cause__`, `__context__` and `__notes__`: a group is not a summary of what went wrong, it is the real exception objects boxed together, and a debugger or a traceback printer can still walk into each one. A group may contain other groups, and nesting is meaningful rather than accidental — it records the shape of the failure, so that "stage two produced three failures, one of which was itself a fan-out" survives into the log. The default traceback rendering prints that tree, numbering each leaf under `+-+----------------` markers, which is why a group in production output is readable instead of being one flattened wall of text. ### What raises one in the standard library The producer to name is `asyncio.TaskGroup`, also new in 3.11: when the tasks started inside an `async with` block fail, leaving the block raises an exception group containing every child failure, so nothing is dropped on the floor. Note what did *not* change: `asyncio.gather` keeps its old contract — with `return_exceptions=False` it propagates the first failure, and with `return_exceptions=True` it returns exception objects as ordinary results. Outside asyncio, groups are mostly raised by your own code and by libraries that fan work out; the point of putting the types in builtins is that everybody raises the same shape instead of each project inventing one. ### The catch that makes `except*` necessary A group is not an instance of what it contains: ```python eg = ExceptionGroup('m', [ValueError('bad')]) isinstance(eg, ValueError) # False ``` So `except ValueError` will not catch it, and neither will `except (ValueError, OSError)`. An ordinary `except` clause matches the type of the propagating object, and the propagating object is the group. That leaves two ways to handle one: * catch the group itself — `except ExceptionGroup as eg:` — and walk `eg.exceptions`, or call `eg.split(...)` / `eg.subgroup(...)` to partition it; * write `except* ValueError:`, which matches *inside* the group, hands the clause a group of the matching leaves, and re-raises whatever no clause matched. This is the single most common misunderstanding about groups, and it has a real consequence: introducing them is a behavioural change, not a free upgrade. A function that starts raising an `ExceptionGroup` where it used to raise a bare `ValueError` will sail straight past every existing `except ValueError` in its callers. ### When to raise one yourself Raise a group when one logical operation genuinely produced several independent failures and the caller needs all of them: validating every field of a payload instead of stopping at the first, processing a batch, or closing a set of resources where more than one close can fail. Do not reach for it when there is a single failure with a cause behind it — that is exception chaining, a different mechanism. And do not use a group as a general-purpose error container that gets passed around and inspected; it is designed to be raised. ### Version note Everything here is 3.11 or later. On 3.10 the names `ExceptionGroup` and `BaseExceptionGroup` do not exist, and `except*` is a syntax error rather than an unsupported feature, so code that must still run on 3.10 cannot use the syntax at all. The semantics are unchanged through 3.14.