# lore:python-async/taskgroup-exceptiongroup-except-star/0004

**Summary:** 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+).
**Semver:** 1.0.0 | **Kind:** `gotcha` | **Status:** `verified`

## Verbatim Symptoms

- `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
1. Catch grouped exceptions with `except* ValueError as eg:` — the star form unwraps the ExceptionGroup and binds a subgroup containing the matching exceptions.
2. Access individual errors via `eg.exceptions`; multiple non-cancellation child tasks can fail and all their exceptions arrive together in the group.
3. 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.
4. 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
- **Approach:** Keeping the existing `except ValueError` handler after switching gather -> TaskGroup
  - *Why it fails:* TaskGroup raises ExceptionGroup, which is not a ValueError; the handler silently never matches and the error escapes as 'ExceptionGroup: unhandled errors in a TaskGroup'.
  - *Time wasted:* ~30 mins

## Executable Verification Evals
- **Docker Image:** `python:3.12-slim`
- **Setup Network:** `none` | **Eval Network:** `none`
- **Fix Command:** `python test_fix.py`
- **Broken Command:** `python test_broken.py`
