Troubleshooting a Migration

Error messages and symptoms that show up after moving asyncio code to anyio or trio, grouped by cause, each with symptom -> cause -> fix. The messages quoted here were reproduced with anyio 4.15 and trio 0.34 on Python 3.13; wording can differ slightly in other versions, so match on the distinctive part. For hangs with no error at all, also use the deadlock debugger.

#Contents

• First: which backend is running?
• asyncio code running under the trio backend
• No running event loop, wrong thread, nested loops
• sniffio errors
• ExceptionGroup surprises
• Cancel scope errors
• Cancellation that does not behave
• Blocking calls
• Task groups that never finish
• Synchronisation primitives and streams
• Library incompatibilities
• Test-suite failures after switching plugins
• migrate_async.py problems
• Step-by-step diagnosis

#First: which backend is running?

Half of all post-migration errors are "asyncio code ran on trio" or "anyio code ran outside any loop". Check before reading the traceback in detail:

import anyio
import sniffio


async def where_am_i() -> None:
    print(sniffio.current_async_library(), anyio.get_cancelled_exc_class().__name__)


anyio.run(where_am_i)                     # asyncio CancelledError
anyio.run(where_am_i, backend="trio")     # trio Cancelled

• In tests, request the anyio_backend_name fixture; the test id also ends in [asyncio] or [trio].
• A traceback that runs through trio/_core/_run.py and then into asyncio/... frames is asyncio code on trio: see the next section.
• LookupError: Backend 'trio' is not available. Install it with: pip install anyio[trio] means trio is not installed in that environment.

#asyncio code running under the trio backend

Anything that needs the asyncio event loop fails under anyio.run(..., backend="trio"), under trio.run, and in the trio column of the test matrix. The failure appears where the asyncio call happens, which can be deep inside a dependency.

Module-level primitives deserve a special look. LOCK = asyncio.Lock() at import time hides until two callers contend for it. Grep for asyncio. in fakes, test helpers and conftest.py too. They run in the trio column and fail there.

#No running event loop, wrong thread, nested loops

anyio.Event() and other primitives can be created outside a loop. They only need one when you await them, so the error shows up at the first await, not at construction.

#sniffio errors

sniffio tells libraries such as httpx and anyio which async library is running. In recent anyio it is an optional dependency of anyio itself, but httpx and others still use it.

#ExceptionGroup surprises

anyio 4 task groups, asyncio.TaskGroup and trio nurseries (trio 0.25+ by default) always raise an ExceptionGroup, even for one failing child. On the anyio asyncio backend the message reads unhandled errors in a TaskGroup (1 sub-exception); on trio, Exceptions from Trio nursery (1 sub-exception).

Never handle a group by catching BaseExceptionGroup and dropping it: it may contain the cancel exception and KeyboardInterrupt.

#Cancel scope errors

Cancel scopes (including every task group, fail_after and move_on_after) are a strict stack per task. They must be exited in reverse order of entry, in the task that entered them.

Causes, from most to least common:

1. yield inside a task group or cancel scope in an async generator. The consumer stops iterating, the generator is closed later from another task or by the loop's async-generator finaliser, and the scope exits there. Fix: a producer task writes into a memory object stream that the caller's task group owns (pattern). An @asynccontextmanager with a single yield is fine.
2. Manual __enter__/__exit__ or AsyncExitStack misuse. Scopes pushed onto an exit stack that is closed in a different task, or in a different order. Fix: use with/async with statements; if you need an exit stack, open and close it in the same task.
3. A scope or task group stored on an object and exited from another method called by another task, for example __aenter__ in a request task and __aexit__ in a shutdown task. Fix: give the object one owner task that runs async with around its whole lifetime (tg.start(service.run)), and talk to it through streams or events.
4. Mixing asyncio cancellation tools with anyio scopes in one task, such as asyncio.timeout() blocks that interleave with anyio.fail_after blocks. Fix: finish migrating that function to anyio scopes.

Lifecycle tip: these errors often surface at interpreter or loop shutdown ("an error occurred during closing of asynchronous generator"), far from the cause. Search for yield in async generators that contain async with anyio.create_task_group(), fail_after, move_on_after or CancelScope.

#Cancellation that does not behave

Under the asyncio backend, anyio scopes also cancel native asyncio awaits (asyncio.wait_for, asyncio.sleep, asyncpg calls) inside them, so mixed code is cancelled correctly while you migrate.

#Blocking calls

A blocking call (time.sleep, requests.get, a sync DB driver, a CPU-heavy loop, a large json.loads) inside async code freezes every task on the loop, and no timeout can interrupt it, because cancellation is only delivered at checkpoints.

Finding blocking calls:

• asyncio backend: anyio.run(main, backend_options={"debug": True}) (or the test param ("asyncio", {"debug": True})) logs Executing <Task ...> took 0.200 seconds for every step over loop.slow_callback_duration (0.1 s by default). trio has no built-in equivalent.
• Grep the migrated modules for time.sleep, requests., urllib, open( and subprocess.run inside async def.
• CPU-bound work does not get faster in a thread because of the GIL: see the GIL analyzer.

#Task groups that never finish

To see what is stuck: anyio.get_running_tasks() lists TaskInfo objects (id, parent_id, name, coro) from inside the loop. On trio, trio.lowlevel.current_root_task() plus a task-tree walk, or an instrument, gives the same picture.

#Synchronisation primitives and streams

#Library incompatibilities

Rule of thumb: a dependency that only says "asyncio" in its docs is asyncio-only until proven otherwise. Grep its source for asyncio.get_event_loop, asyncio.get_running_loop, loop.create_future, or asyncio.Future.

#Test-suite failures after switching plugins

#migrate_async.py problems

#Step-by-step diagnosis

1. Reproduce on one backend at a time. pytest -k asyncio then pytest -k trio. A failure only on trio points to asyncio leftovers or ordering assumptions; a failure on both points to semantics (grouping, cancellation).
2. Read the bottom of the traceback for the frame that touches asyncio. Leftover calls live there. python scripts/migrate_async.py <that file> shows the rule id and the fix.
3. Unwrap groups. Print eg.exceptions recursively. The leaf with the earliest timestamp in the logs is usually the root cause; the rest are cleanup failures caused by the cancellation it triggered.
4. Check cancel scopes. Any yield inside a scope in an async generator? Any scope stored on an object? Any __aenter__/__aexit__ split across tasks?
5. Check handlers. Every except that can catch the cancel class re-raises. Every await in finally is shielded and bounded.
6. Check for blocking. Run with asyncio debug=True and look for took 0.xxx seconds warnings.
7. Check for hangs. Add a fail_after guard around the suspect block, then list tasks with anyio.get_running_tasks() before it fires.
8. Fix, then add a regression test on both backends: cancellation tests assert cleanup ran; group tests use pytest.RaisesGroup; timing tests use MockClock (see testing-with-anyio-and-trio.md).