Exception Groups & except*

Also Known As

TL;DR

Explanation

ExceptionGroup (Python 3.11) wraps multiple exceptions raised simultaneously. except* syntax catches specific exception types from the group while letting unmatched exceptions propagate. asyncio.TaskGroup (Python 3.11) runs all tasks and collects all failures in an ExceptionGroup — unlike asyncio.gather which only surfaces the first failure. The except* handler receives an ExceptionGroup containing only the matching exceptions.

Common Misconception

Why It Matters

Common Mistakes

• Using except* for single exceptions — it is specifically for ExceptionGroup
• Not handling remaining unmatched exceptions — they still propagate
• Forgetting asyncio.TaskGroup requires Python 3.11+ — use asyncio.gather for older versions
• Not iterating eg.exceptions to see individual exception details

Code Examples

# asyncio.gather — only first error visible:
async def run_all():
    results = await asyncio.gather(task1(), task2(), task3())
    # If task1 and task3 both fail:
    # Only task1's error is raised — task3's error is silently lost

# asyncio.TaskGroup — all errors collected:
async def run_all():
    async with asyncio.TaskGroup() as tg:
        t1 = tg.create_task(task1())
        t2 = tg.create_task(task2())
        t3 = tg.create_task(task3())
    # All tasks ran; both failures collected in ExceptionGroup

try:
    await run_all()
except* ValueError as eg:
    for exc in eg.exceptions:
        print(f'ValueError from task: {exc}')
except* ConnectionError as eg:
    for exc in eg.exceptions:
        print(f'Connection failed: {exc}')

Tags

Related Terms

References

• https://peps.python.org/pep-0654/