verified
lore:python-async/taskgroup-exceptiongroup-except-star/0004 (v1.0.0)
asyncio.TaskGroup wraps child-task exceptions in an ExceptionGroup, so a plain `except ValueError` around the `async with` block does NOT catch them and the error escapes; use `except*` (Python 3.11+).
Verbatim Symptoms (Primary Search Key)
- ExceptionGroup: unhandled errors in a TaskGroup
- except clause did not catch exception raised inside TaskGroup
- TaskGroup raised ExceptionGroup instead of the original exception
- handler stopped working after migrating from asyncio.gather to TaskGroup
Problem Statement
TaskGroup cancels sibling tasks when one fails (unlike gather) and then, on exiting the async-with block, re-raises ALL child exceptions bundled in an ExceptionGroup. A conventional `except ValueError:` around the block does not match an ExceptionGroup, so the exception is not caught and propagates uncaught, crashing the program. Note on cancellation: TaskGroup delivers CancelledError to sibling tasks internally (triggering their finally/except CancelledError blocks for cleanup), but strips CancelledError from the final ExceptionGroup raised at the block exit so only non-cancellation child errors arrive in the group.
Correct Procedure
- Catch grouped exceptions with `except* ValueError as eg:` — the star form unwraps the ExceptionGroup and binds a subgroup containing the matching exceptions.
- Access individual errors via `eg.exceptions`; multiple non-cancellation child tasks can fail and all their exceptions arrive together in the group.
- Ensure sibling tasks use `finally:` or `except asyncio.CancelledError:` for cleanup — TaskGroup cancels siblings immediately when one task fails, and their CancelledError is handled internally during block teardown.
- If you must interoperate with code that expects a bare exception, unwrap explicitly: catch the ExceptionGroup, inspect `.exceptions`, and re-raise the single one.
Anti-Patterns
- Using plain `except SomeError:` around a TaskGroup block — it will not catch exceptions wrapped in an ExceptionGroup.
- Assuming TaskGroup behaves like gather for error handling — gather raises the first bare exception; TaskGroup always groups.
- Mixing `except` and `except*` in the same try statement — Python forbids it and raises SyntaxError.
Documented Dead Ends
- Keeping the existing `except ValueError` handler after switching gather -> TaskGroup: TaskGroup raises ExceptionGroup, which is not a ValueError; the handler silently never matches and the error escapes as 'ExceptionGroup: unhandled errors in a TaskGroup'. (~30 mins wasted)