pytest "asyncio.TimeoutError" in a test in CI

By Kaveh Alemi·Latchkey

An asyncio.wait_for (or similar) timed out because the awaited coroutine did not complete in time. On a slower CI runner, or against an unmocked network call, the operation legitimately exceeds the deadline.

What this error means

An async test fails with "asyncio.exceptions.TimeoutError" (or bare "TimeoutError") at an await wait_for(...), intermittently and more often under CI load.

    result = await asyncio.wait_for(fetch(url), timeout=1.0)
asyncio.exceptions.TimeoutError

Common causes

The operation is slower than the timeout on CI

A timeout tuned to a fast developer machine is too tight for a busier, slower CI runner.

An unmocked external call hangs

A test that hits a real network/service can stall when that dependency is slow or unreachable in CI.

How to fix it

Mock external calls in tests

Replace real I/O with a fake so the awaited operation is fast and deterministic.

async def fake_fetch(url):
    return {"ok": True}

monkeypatch.setattr(mod, "fetch", fake_fetch)

Give CI a realistic timeout

Raise the timeout for CI so a slower-but-correct run is not failed for being slow.

result = await asyncio.wait_for(fetch(url), timeout=10.0)

How to prevent it

• Mock network and external services in unit tests.
• Size async timeouts for the slowest expected runner.
• Avoid real I/O in tests that assert on timing.

Frequently asked questions

Related guides

References

• Python documentation
• pip documentation
• GitHub Actions documentation