← Back to Home

asyncio Cancellation: Six Silent Failures, Reproduced

Pythonasyncioconcurrency

TL;DR: In asyncio, cancellation is an exception and a timeout is a second layer wrapped around that exception. Six things go wrong here without a single line in your logs: except Exception cannot see CancelledError; except OSError swallows timeouts along with network errors; a wait_for deadline can be eaten by the inner coroutine and come back as a normal return value; asyncio.timeout() cannot interrupt a blocking call; after shield the inner exception is never retrieved; and run_in_executor's cancel() only flips a flag. I ran all six on CPython 3.13.14 under Windows 11. Every case below has a runnable script and a fix.

Why none of these six raises anything

asyncio's cancellation has exactly two moving parts. Cancelling means throwing asyncio.CancelledError into a task at one of its await points. A timeout means a timer fires, cancels the current task, and the context manager converts that CancelledError into a TimeoutError on the way out.

The official docs put the second half in a Note under asyncio.timeout(): "The asyncio.timeout() context manager is what transforms the asyncio.CancelledError into a TimeoutError, which means the TimeoutError can only be caught *outside* of the context manager."

Three consequences follow, and all six traps derive from them:

Environment and reproduction

python -V
# Python 3.13.14

Doc quotes were read from docs.python.org/3 on 2026-11-01. Every number below comes from this machine: CPython 3.13.14, Windows 11.

Trap 1: except Exception misses the cancellation

import asyncio

async def child():
    try:
        await asyncio.sleep(5)
    except Exception:                 # looks like a catch-all
        print("child caught something")
        return "swallowed"
    return "done"

async def main():
    t = asyncio.create_task(child())
    await asyncio.sleep(0.1)
    t.cancel()
    print(await t)                    # never reached

asyncio.run(main())

Symptom: await t raises CancelledError and the except Exception inside child prints nothing. If this were a background task (created and never awaited), nobody would see the exception and the process would exit 0.

Evidence: asyncio.CancelledError.__mro__ is CancelledError -> BaseException -> object, and issubclass(CancelledError, Exception) is False. Docs: "Changed in version 3.8: CancelledError is now a subclass of BaseException rather than Exception."

Fix: put cleanup in finally; if you must catch it, catch asyncio.CancelledError explicitly and raise after cleanup.

Trap 2: except OSError eats the timeout too

import asyncio

async def slow():
    await asyncio.sleep(10)

async def main():
    try:
        await asyncio.wait_for(slow(), timeout=0.05)
    except OSError:                   # meant for network errors
        print("network branch hit")

asyncio.run(main())

Symptom: it prints "network branch hit" and no TimeoutError shows up anywhere, so the caller concludes the peer dropped the connection.

Cause: since Python 3.11 asyncio.TimeoutError is an alias of the built-in TimeoutError — "Changed in version 3.11: This class was made an alias of TimeoutError." — and the built-in TimeoutError sits under OSError in the exception hierarchy (TimeoutError -> OSError -> Exception -> BaseException). So except OSError collects timeouts for free. On 3.10 and earlier the two classes were unrelated, which is why the same snippet behaves differently on an older interpreter.

Fix: stop using bare except OSError for network code. Catch TimeoutError precisely, or except (TimeoutError, asyncio.TimeoutError) for code that must run on both sides of the 3.11 change.

Trap 3: wait_for's deadline becomes a fake success

import asyncio, time

async def stubborn():
    try:
        await asyncio.sleep(3)
    except asyncio.CancelledError:
        return "ignored cancel"       # cleanup done, then return

async def main():
    t0 = time.monotonic()
    r = await asyncio.wait_for(stubborn(), timeout=0.05)
    print(round(time.monotonic() - t0, 2), r)

asyncio.run(main())

Measured output: 0.06 ignored cancel. No TimeoutError. The caller receives a perfectly ordinary string.

Two documented facts explain it. First, since 3.12 wait_for is implemented on top of asyncio.timeout(): "Changed in version 3.12: Implemented using asyncio.timeout(), a coroutine passed as *aw* is no longer wrapped in a Task when *timeout* is positive." With a positive timeout the coroutine is no longer wrapped in its own task, so the cancellation lands on the *same* task's await point and the inner try/except catches it. Second, the docs state the consequence directly in the Task cancellation section: "The asyncio components that enable structured concurrency, like asyncio.TaskGroup and asyncio.timeout(), are implemented using cancellation internally and might misbehave if a coroutine swallows asyncio.CancelledError."

This is not a one-off. CPython's issue about wait_for hiding cancellation is still open: gh-86296 (formerly bpo-42130), titled "AsyncIO's wait_for can hide cancellation in a rare race condition". The Tribler project's issue #7570 lists the same family (#86296, #87555, #81839) as a cause of freezes in production.

Fix: re-raise. If you genuinely want to suppress cancellation, the official escape hatch is uncancel():

except asyncio.CancelledError:
    asyncio.current_task().uncancel()
    return "suppressed"

Measured difference: the raise version throws TimeoutError at 0.06s; the uncancel() version returns normally at 0.06s. The first means "the timeout fired", the second means "I explicitly do not want a timeout". Both are acceptable. Catching without re-raising and without uncancel() is the bug.

Trap 4: asyncio.timeout cannot interrupt a blocking call

import asyncio, time

async def main():
    async with asyncio.timeout(0.05):
        time.sleep(0.6)

asyncio.run(main())

Measured: it exits cleanly after 0.60s with no TimeoutError — 1200% of the declared deadline.

Cause: cancellation can only be delivered at an await point. During time.sleep(0.6) the event loop is completely stopped, so the timer callback never gets a chance to run.

Diagnostic command — dev mode prints the stuck callback:

PYTHONDEVMODE=1 python your_script.py
# Executing > took 0.303 seconds

Fix: wrap blocking work in await asyncio.to_thread(func), or push the whole synchronous block into run_in_executor, and put the timeout outside of that.

Trap 5: after shield, nobody retrieves the inner exception

import asyncio

async def inner():
    await asyncio.sleep(0.1)
    raise RuntimeError("inner blew up after outer gave up")

async def main():
    sh = asyncio.ensure_future(inner())
    try:
        await asyncio.wait_for(asyncio.shield(sh), timeout=0.02)
    except TimeoutError:
        print("outer timed out")
    await asyncio.sleep(0.4)

asyncio.run(main())

Symptom: it prints "outer timed out", then 0.4s later stderr shows this:

Task exception was never retrieved
future:  exception=RuntimeError('inner blew up after outer gave up')>

Cause: shield means exactly what it says — "except that if the coroutine containing it is cancelled, the Task running in something() is not cancelled". After the timeout returns, that task keeps running; when it raises, no one awaits it, so asyncio can only log at collection time. The same docs page carries an Important note that is easy to skip: "Save a reference to tasks passed to this function, to avoid a task disappearing mid-execution. The event loop only keeps weak references to tasks." Without a reference the task can be garbage collected mid-flight.

Fix: keep the reference and retrieve the exception in a callback.

import asyncio

def _consume(t: asyncio.Task) -> None:
    if not t.cancelled():
        t.exception()                 # retrieve it, avoid "never retrieved"

async def main():
    sh = asyncio.ensure_future(inner())
    sh.add_done_callback(_consume)
    try:
        await asyncio.wait_for(asyncio.shield(sh), timeout=0.02)
    except TimeoutError:
        sh.cancel()                   # you no longer want the result

Trap 6: run_in_executor's cancel only flips a flag

import asyncio, threading, time

def blocking(counter, done):
    for _ in range(20):
        time.sleep(0.05)
        counter[0] += 1
    done.set()

async def main():
    counter, done = [0], threading.Event()
    loop = asyncio.get_running_loop()
    fut = loop.run_in_executor(None, blocking, counter, done)
    await asyncio.sleep(0.12)
    fut.cancel()
    print("cancelled()", fut.cancelled(), "n =", counter[0])
    await asyncio.sleep(0.3)
    print("after 0.3s n =", counter[0], "thread done?", done.is_set())

asyncio.run(main())

Measured: cancelled() True n = 2, then after 0.3s n = 8 thread done? False. The thread ran to n = 20 before finishing. fut.cancelled() being True only means the asyncio-side future was marked; the worker thread has no interruption mechanism.

Fix: cooperative stopping — pass a threading.Event as a stop flag and check it every iteration. If you need a hard kill, use ProcessPoolExecutor, where a process can be terminated.

Two more silent behaviours worth knowing

Reference table: what actually happens after cancellation

Call patternMeasured result
wait_for(coro, 0.05), inner swallows cancelreturns the business value at 0.06s, no exception
asyncio.timeout(0.05), inner swallows cancelexits normally at 1.06s, no exception
asyncio.timeout(0.05) around time.sleep(0.6)exits normally at 0.60s, no exception
wait_for(shield(task), 0.02)outer TimeoutError, inner keeps running until it raises
run_in_executor(...) then cancel()cancelled() True, thread still runs all 20 iterations
TaskGroup child does raise CancelledErrorexits normally, no exception
gather child does raise CancelledErrorraises CancelledError
gather(return_exceptions=True) with a cancelled taskthe cancellation appears as an object in the result list

That last row deserves its own sentence: [type(x).__name__ for x in r] measured ['CancelledError', 'NoneType']. Cancellation is disguised as a result. Any downstream code that only checks "does this slot have a value" will treat a cancelled task as one that returned empty.

Five rules that hold

1. After except asyncio.CancelledError, raise once cleanup is done; to suppress, call uncancel().

2. Do not use except OSError as a network catch-all; catch TimeoutError precisely.

3. Keep cleanup short: shield any long await inside finally, or avoid long waits there altogether.

4. Move every blocking call to to_thread, otherwise the timeout is decorative.

5. Keep references to tasks from shield and create_task, and register a callback that retrieves exceptions.

Troubleshooting: five real messages and their fixes

Error 1: TypeError: Passing coroutines is forbidden, use tasks explicitly.

Symptom: await asyncio.wait([quick()]) raises TypeError, and stderr also shows RuntimeWarning: coroutine 'quick' was never awaited.

Cause: since 3.11 asyncio.wait() rejects bare coroutines.

Fix: tasks = [asyncio.create_task(quick())] and then await asyncio.wait(tasks).

Error 2: Task exception was never retrieved

Symptom: the outer call already timed out, and seconds later stderr dumps a full RuntimeError traceback.

Cause: shield let the inner task continue and nobody awaited its failure.

Fix: see Trap 5 — keep the reference and drain exception() in a done callback.

Error 3: TimeoutError landing in the network branch

Symptom: logs show the except OSError branch, and the incident is filed as a peer disconnect.

Cause: since 3.11 asyncio.TimeoutError is TimeoutError is True, and TimeoutError is an OSError subclass.

Fix: split except TimeoutError and except OSError into two branches with separate handling.

Error 4: an ExceptionGroup with a single ValueError while a sibling's finally ran

Symptom: the group carries one element, yet another task printed cleanup logs, so it looks like something was cancelled with no explanation.

Cause: the sibling received CancelledError, which the docs explicitly exclude from the group.

Fix: track cancellations yourself; do not expect the exception aggregate to explain them.

Error 5: orphan tasks cancelled silently at shutdown

Symptom: a create_task result was never stored, the main coroutine returned, and its finally ran exactly once with no logging.

Cause: asyncio.run() cancels all pending tasks before closing the loop.

Fix: cancel() and await them explicitly before returning, so the teardown is observable.

Where these conclusions stop

FAQ

Q: Is except BaseException the safest option?

No. It also catches KeyboardInterrupt and SystemExit, so Ctrl+C stops working. Catch asyncio.CancelledError specifically and let the rest bubble.

Q: Is except asyncio.TimeoutError still meaningful after 3.11?

Yes, but know that it is now the same class as TimeoutError, so the catch range is identical. Writing the old name only preserves readability.

Q: Does cancel() returning True mean the task was cancelled?

No. It means a cancellation request was registered. Measured: cancelling an already-finished task returns False; cancelling an executor future makes cancelled() True while the thread still runs to completion.

Q: When is Task.cancelling() useful?

When you need to know how many cancels arrived. Measured: after the first cancel cancelling() is 1; calling uncancel() brings it to 0, after which the task returns normally and cancelled() is False.

Q: Why did my cleanup code never run?

Two usual reasons: the cleanup sits inside except Exception, which cancellation never reaches; or it sits in finally and awaits something long, so a second cancel cuts it off.

This is a pure engineering post-mortem; it contains no affiliate links. Related reading: the same silent-timeout problem at the process layer in the subprocess piece, retries stacked on top of timeouts in the requests and tenacity piece, and time.sleep freezing the loop inside async nodes in the LangGraph streaming piece.

👉 Join Xiaomi MiMo Platform: Leading AI model platform with cost-effective inference

👉 Join Aliyun AI: Top AI products with exclusive coupons for business innovation

📌 This article was AI-assisted generated and human-reviewed | TechPassive — An AI-driven content testing site focused on real tool reviews

🔗 Recommended Tools

These are carefully selected tools. Using our affiliate links supports us to keep producing quality content:

As an Amazon Associate, I earn from qualifying purchases at no extra cost to you.

☁️ DigitalOcean Cloud ⚡ Vultr VPS 🤖 QoderWork CN (Refer & Earn) ☁️ Aliyun AI Products 📚 WordPress Books 🧠 AI & LLM Books 🏗️ System Design Books 🐳 Docker & K8s Books 🐧 Linux Admin Books 🐍 Python Books 🗄️ Database Books 🚀 DevOps & SRE Books 🤖 Xiaomi MiMo Platform
← Back to Home