Skip to content
Tutorials Center
My learning

Topics

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.

Python
raise ExceptionGroup("validation failed", [
    ValueError("age must be positive"),
    TypeError("name must be a string"),
])

Try it

Python Raising and handling a group with except*

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 split(), subgroup() and unhandled members

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

Python
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 plain except, which takes the first match, each except* 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* ValueError hands you an ExceptionGroup containing it.
  • Leftovers are re-raised. Members not matched by any clause are raised again in a new group after the try statement, with the original traceback information kept.
  • Cannot mix except and except* in the same try statement, and break, continue and return are not allowed inside an except* block.
  • Nesting is allowed. A group may contain other groups; split() and subgroup() 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 an ExceptionGroup when child tasks fail, so use except* around it. Plain except ValueError will not catch a ValueError wrapped in a group.
  • Subclassing needs care: override derive() so split() and except* can build matching groups.
  • Versions before 3.11 have no such feature; the exceptiongroup backport package provides it.