An async FastAPI test that awaits a database call fails with "RuntimeError: ... attached to a different loop"; why does this happen, and how do you fix it?
answer
- objects bound to their creating loop
- the client's portal thread
- a new loop per bare request
- one loop for test and app
- resources created at startup
basics
~20 sAsyncio objects belong to the loop that made them, and TestClient runs the app on its own portal loop, new per request outside a with block. Put test and app on one loop: AsyncClient with ASGITransport, resources created in the lifespan.
solid answer
~50 sAsyncio futures, locks and driver connections are bound to the loop that created or first used them, and awaiting one from another loop raises a `RuntimeError` ("attached to a different loop" for a future, "is bound to a different event loop" for a lock or event). `TestClient` never runs the app on the test's loop: it uses a blocking portal with its own loop in another thread, and outside a `with` block a new one per request. So an async test that opens a connection and then calls the app through `TestClient` hands the app an object from the wrong loop, and a module-level pool first used by one bare request can fail in the next. The fix is one loop: in async tests use `httpx.AsyncClient` with `ASGITransport`, create loop-bound resources in the `lifespan` (entered with `LifespanManager`), and in sync tests keep requests inside one `with TestClient(app)` block.
code
python · 42 linesimport asyncio
import pytest
from fastapi import FastAPI
from fastapi.testclient import TestClient
from httpx import ASGITransport, AsyncClient
app = FastAPI()
pending = {}
@app.get("/items")
async def list_items():
await pending["query"] # stands in for a driver call bound to the test's loop
return []
@pytest.fixture
def anyio_backend():
return "asyncio"
def start_query() -> None:
loop = asyncio.get_running_loop()
pending["query"] = loop.create_future()
loop.call_later(0.01, pending["query"].set_result, None)
@pytest.mark.anyio
async def test_testclient_inside_async_test():
start_query()
with TestClient(app) as client:
with pytest.raises(RuntimeError, match="attached to a different loop"):
client.get("/items")
@pytest.mark.anyio
async def test_asyncclient_same_loop():
start_query()
async with AsyncClient(transport=ASGITransport(app=app), base_url="http://test") as ac:
response = await ac.get("/items")
assert response.json() == []go deeper
Know that asyncio objects belong to one event loop and that TestClient runs the app on a loop of its own, not on the test's.
Explain the portal: one loop inside a with block, a new loop per bare request, and why that turns shared async objects into different-loop errors.
Diagnose from the traceback: find where the object was created, confirm two loops, then move creation into the lifespan or move the test onto AsyncClient.
Set suite rules that prevent it: no TestClient inside async tests, loop-bound resources only in the lifespan, and one shared fixture that owns the client.
## Why asyncio objects belong to a loop An **event loop** runs coroutines and owns the I/O they wait on. Many asyncio objects are tied to the loop that created them or first used them: futures and tasks, locks and events once something has waited on them, and the connections and pools of async database drivers, whose sockets are registered with that loop. Awaiting such an object from a **different** loop raises a `RuntimeError`. The wording depends on the object: - a future: `Task <...> got Future <...> attached to a different loop`; - a lock or event: `<asyncio.locks.Event ...> is bound to a different event loop`; - driver objects may raise their own variants, such as an error about a closed event loop. The error is never about the database server. It says two loops met. ## Where `TestClient`'s loop comes from `TestClient` never runs the app on the test's loop. Every request goes through a **blocking portal**: a separate thread running its own event loop. - Inside `with TestClient(app) as client:` one portal, and so one loop, serves the lifespan and every request in the block. - With a bare client, **each request opens a new portal**, so each request runs on a brand-new loop. ## Three ways a suite triggers the error 1. **`TestClient` in an `async def` test.** The test opens a connection, or schedules a query, on its own loop, then calls the app through `TestClient`. The app awaits it on the portal's loop and fails. 2. **A module-level resource and a bare client.** A pool or `asyncio.Event` created at import is bound by the first request's loop. The second bare request runs on a new loop and fails, while the first one passed. 3. **Resources made on the wrong loop at startup.** Code that creates a client outside the loop that will serve requests, for example at import time or in a fixture running on another loop, breaks the first time a request awaits it. FastAPI's async tests page carries the same advice: create objects that need an event loop only inside async code that runs on the serving loop. Its tip still names an `@app.on_event("startup")` callback; in FastAPI 0.143 that place is the `lifespan`. ## A minimal reproduction The code example shows the mechanism with no database at all: 1. `start_query()` creates a pending future on the **test's** loop and schedules its result a few milliseconds later, standing in for a driver call. 2. The endpoint awaits that future. 3. Called through `TestClient`, the endpoint runs on the portal's loop, and awaiting a future from another loop raises `RuntimeError: ... attached to a different loop` at once. 4. Called through `AsyncClient` with `ASGITransport`, the endpoint runs on the test's own loop, the future resolves, and the test passes. ## Fixes | Situation | Fix | |---|---| | An async test must await a resource the app also uses | Replace `TestClient` with `httpx.AsyncClient(transport=ASGITransport(app=app), base_url=...)`, so the app runs on the test's loop | | The app needs startup resources in that async test | Enter `LifespanManager(app)` in the test and pass `manager.app` to the transport | | Sync tests with loop-bound app resources | Run every request inside one `with TestClient(app)` block, and create the resources in the `lifespan` | | A resource is created at import time | Move it into the `lifespan` and yield it into state, or create a short-lived one per request in a dependency | Wrapping the client in a `with` block does **not** fix case 1: the block gives you one loop, but it is still the portal's loop, not the test's. Passing `backend="asyncio"` does not help either; asyncio is already the default, and the portal still owns its loop. ## Diagnosing it quickly - Log `id(asyncio.get_running_loop())` in the endpoint and in the test: two values confirm two loops. - Find **where** the failing object was created: in the test body, at import, in a fixture or in the lifespan. - Check whether the suite mixes `TestClient` with `async def` tests; that pairing is the most common source. - If a long-lived async fixture outlives the loop it was created on, the fix is in fixture and loop scoping, covered with pytest's async plugins. - Reproduce with one test at a time: a test that passes alone and fails after another is usually case 2.
- Why does a with TestClient(app) block not fix an async test that opens its connection in the test body?The block gives the lifespan and every request one loop, but that loop belongs to the client's portal thread, not to the test. A connection the test body opened is still bound to the test's loop, so the app fails the same way. Only `AsyncClient` with `ASGITransport` runs the app on the test's own loop.
- Where should a FastAPI app create its async database engine so tests and production behave alike?In the `lifespan`, yielded into state, so it is created on the loop that serves requests, never at import time and never lazily on whichever loop the first request happens to run. Tests then enter the lifespan on the loop that serves their requests: one `with TestClient(app)` block for sync tests, or `LifespanManager` plus `ASGITransport` for async ones.
A loop-bound object is like a cloakroom ticket: it is valid only at the venue that issued it. TestClient serves the app at a different venue from the test, so the test's ticket is refused there.
- TestClient runs the app on the pytest test's own event loop
- A with TestClient block lets the app use connections the test opened
- The error means the database server dropped the connection
- Passing backend="asyncio" makes TestClient share the test's loop
- Asyncio objects are bound to threads, so run_in_threadpool fixes it