Python Reference ยท Exceptions
Python ExceptionGroup and except*
Reference for Python ExceptionGroup, BaseExceptionGroup and except* (3.11+): bundling several errors, matching by type, split(), subgroup() and asyncio use.
An ExceptionGroup bundles several unrelated exceptions into one object, so they can be raised and handled together. It was added in Python 3.11 together with the except* clause, which handles the members of a group by type. Typical sources are concurrent tasks (asyncio.TaskGroup) that fail at the same time, and validation code that wants to report every problem rather than the first one.
BaseExceptionGroup can hold any BaseException; ExceptionGroup holds only Exception subclasses and is itself an Exception. Creating a BaseExceptionGroup whose members are all ordinary exceptions gives you an ExceptionGroup automatically.
raise ExceptionGroup("validation failed", [ ValueError("age must be positive"), TypeError("name must be a string"), ])
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.
Syntax
try: run_tasks() except* ValueError as group: ... # group is an ExceptionGroup of the ValueErrors except* (OSError, KeyError) as group: ... ExceptionGroup(message, exceptions) group.split(condition) # (matching, rest) group.subgroup(condition) # matching part, or None
| Name | Description |
|---|---|
message |
A description of the group (read as group.message; also str(group) includes the member count). |
exceptions |
A tuple of the member exceptions (a non-empty sequence is required). |
split(condition) |
Returns (match, rest); either may be None. The condition is an exception type, a tuple of types, or a function. |
subgroup(condition) |
Returns a group with the matching members, or None. |
derive(excs) |
Creates a new group of the same kind and metadata (override it in subclasses). |
Raises when: you build a group with an empty list (ValueError), pass a non-sequence (TypeError), or put non-Exception members into an ExceptionGroup (TypeError).
Usage notes
except*runs every matching clause. Unlike plainexcept, which takes the first match, eachexcept*clause receives the matching members, and clauses can run one after another for a single group.- Always receives a group. Even when a plain
ValueError(not in a group) is raised,except* ValueErrorhands you anExceptionGroupcontaining it. - Leftovers are re-raised. Members not matched by any clause are raised again in a new group after the
trystatement, with the original traceback information kept. - Cannot mix
exceptandexcept*in the sametrystatement, andbreak,continueandreturnare not allowed inside anexcept*block. - Nesting is allowed. A group may contain other groups;
split()andsubgroup()keep the structure and prune empty branches. - Raising inside
except*adds that exception to the result group, so you can handle some members and raise new ones. - Use
add_note()(3.11+) to attach extra text to members; notes appear in the traceback. - asyncio.
asyncio.TaskGroup(3.11+) raises anExceptionGroupwhen child tasks fail, so useexcept*around it. Plainexcept ValueErrorwill not catch aValueErrorwrapped in a group. - Subclassing needs care: override
derive()sosplit()andexcept*can build matching groups. - Versions before 3.11 have no such feature; the
exceptiongroupbackport package provides it.