Maaz Zindani

Loading the index…

↑↓ move↵ openesc close4072 pages
Node.js, PHP and APIs

Python asyncio: Task was destroyed but it is pending

ErrorTask was destroyed but it is pending!

Short answer

A task was still unfinished when Python threw it away. Either nothing held a reference to it, so it was garbage collected mid-run, or the program reached the end of the loop without awaiting it. Keep a strong reference, and await every task with TaskGroup.

  • Applies to Python 3.12, Python 3.13
  • Updated
  • By Maaz Zindani, Senior Software Engineer

Fix it fast

  1. 1Find out which cause you have

    Run the program in asyncio debug mode. It shows the traceback where each unfinished task was created.

    PYTHONASYNCIODEBUG=1 python -X dev main.py
  2. 2Match what you see, then jump to its fix

    1. 1asyncio.create_task(job()) is called and the result is not stored anywhereA fire-and-forget task has no referenceFix
    2. 2The warning prints once, at shutdown, for tasks that were created but never awaitedmain() returns while tasks are still runningFix
    3. 3One job failed, the program moved on or ended, and the others are reported as pendinggather() raised and left sibling tasks runningFix
    4. 4RuntimeWarning: coroutine '...' was never awaitedA coroutine was called but never scheduledFix

What does the error look like?

  • Task was destroyed but it is pending!
  • RuntimeWarning: coroutine '...' was never awaited
  • Task exception was never retrieved

Cause 1 of 4

A fire-and-forget task has no reference

1Check

The event loop keeps only weak references to tasks, so a task nothing else refers to can be garbage collected before it is done.

grep -rn "create_task(" . --include=*.py

2Fix

Keep each task in a set, and let it remove itself when finished.

background = set()

def spawn(coro):
    task = asyncio.create_task(coro)
    background.add(task)
    task.add_done_callback(background.discard)
    return task

3Verify

The background job now runs to the end and the warning stops.

PYTHONASYNCIODEBUG=1 python main.py

Confirmed by docs.python.org

Did this fix it?

Cause 2 of 4

main() returns while tasks are still running

1Check

Tasks started with a bare create_task() are never awaited by anything. A task nobody awaits also loses its exceptions, which asyncio reports later as Task exception was never retrieved.

PYTHONASYNCIODEBUG=1 python main.py

2Fix

Create the tasks inside an asyncio.TaskGroup. All tasks are awaited when the block exits, and their failures come back as an ExceptionGroup.

async def main():
    async with asyncio.TaskGroup() as tg:
        for i in range(10):
            tg.create_task(work(i))

3Verify

The program ends only after all ten jobs finish, and the warning is gone.

python main.py

Confirmed by docs.python.org

Did this fix it?

Cause 3 of 4

gather() raised and left sibling tasks running

1Check

With return_exceptions left at False, gather() passes the first exception to the caller but does not cancel the other awaitables, which keep running.

grep -rn "gather(" . --include=*.py

2Fix

Use a TaskGroup, which cancels the remaining tasks when one fails, or pass return_exceptions=True and handle each result.

results = await asyncio.gather(*jobs, return_exceptions=True)
for r in results:
    if isinstance(r, Exception):
        print("job failed:", r)

3Verify

Make one job raise on purpose; the others finish or are cancelled and nothing is reported as destroyed.

python main.py

Confirmed by docs.python.org

Did this fix it?

Cause 4 of 4

A coroutine was called but never scheduled

1Check

Calling an async function without await or create_task does not run it.

python -X dev main.py

2Fix

Add await in front of the call, or wrap it in asyncio.create_task() and keep the reference as above.

async def main():
    await test()

3Verify

The warning no longer prints.

python -X dev main.py

Confirmed by docs.python.org

Did this fix it?

How do I stop it coming back?

  • Treat every create_task() result as something you must hold and await.
  • Prefer TaskGroup over bare create_task and gather in new code.
  • Run tests with python -X dev so unawaited coroutines show up early.

Sources

How was this page made?

I drafted this page with AI assistance from the official documents listed under Sources. Every cause above names the document that confirms it. I have not reproduced this fix on a machine of my own yet, so read it as documented guidance, not a test report. Found a mistake? Tell me.

Which stack is behind this page?

Projects of mine built on the same technologies:

Related fixes

Back end

npm install fails inside a node:alpine Docker build

Docker Node Alpine Image Build Fails on node-gyp

The node alpine images ship almost nothing beyond Node.js, so a native module that node-gyp must compile has no Python, make or C++ compiler.

2 causes, each with a fix

Next step

Want this handled for good?

I look after servers, apps and releases end to end. Tell me what keeps breaking.