Introduction

When several asyncio tasks are running together, you often want fail-fast behavior: if one task crashes, cancel the rest and stop the whole operation. The right solution depends on your Python version.

In modern Python, asyncio.TaskGroup is the cleanest answer because it automatically cancels sibling tasks when one fails. In older code, you usually need to create tasks manually, catch the exception, cancel the remaining tasks, and wait for the cancellations to finish.

The Modern Solution: TaskGroup

If you are on Python 3.11 or later, use asyncio.TaskGroup. It was designed for structured concurrency.

1import asyncio
2
3async def worker(name, delay, should_fail=False):
4    await asyncio.sleep(delay)
5    if should_fail:
6        raise RuntimeError(f"{name} failed")
7    print(f"{name} done")
8
9async def main():
10    async with asyncio.TaskGroup() as tg:
11        tg.create_task(worker("a", 1))
12        tg.create_task(worker("b", 2, should_fail=True))
13        tg.create_task(worker("c", 5))
14
15asyncio.run(main())

If task b fails, the task group cancels the other running tasks and then re-raises the failure as part of an exception group.

This is the preferred pattern because cancellation and cleanup are handled in one place.

How to Do It Before TaskGroup

Older asyncio code often used asyncio.gather, but gather alone does not give you the cleanest fail-fast control unless you add explicit cancellation logic.

A robust manual pattern looks like this:

1import asyncio
2
3async def worker(name, delay, should_fail=False):
4    await asyncio.sleep(delay)
5    if should_fail:
6        raise RuntimeError(f"{name} failed")
7    print(f"{name} done")
8
9async def main():
10    tasks = [
11        asyncio.create_task(worker("a", 1)),
12        asyncio.create_task(worker("b", 2, should_fail=True)),
13        asyncio.create_task(worker("c", 5)),
14    ]
15
16    try:
17        await asyncio.gather(*tasks)
18    except Exception as exc:
19        for task in tasks:
20            task.cancel()
21        await asyncio.gather(*tasks, return_exceptions=True)
22        raise exc
23
24asyncio.run(main())

The second gather(..., return_exceptions=True) is important. It gives cancelled tasks a chance to finish their cancellation path cleanly instead of leaving them half-finished.

Why Plain gather Can Be Misleading

Developers often assume await asyncio.gather(*tasks) automatically means “if one fails, stop everything.” The behavior is more nuanced.

If one task raises an exception, gather propagates that exception to the caller. But other tasks may still need explicit cancellation handling, especially if you created them separately and want to control shutdown behavior predictably.

That is why structured concurrency with TaskGroup is such a useful improvement.

Make Your Tasks Cancellation-Friendly

Cancellation only works well if tasks cooperate. A task should not swallow asyncio.CancelledError unless it re-raises it after cleanup.

1async def worker():
2    try:
3        await asyncio.sleep(10)
4    except asyncio.CancelledError:
5        print("cleaning up")
6        raise

If tasks block in non-awaiting code or suppress cancellation incorrectly, “cancel all tasks” becomes much less reliable.

When return_exceptions=True Is Not the Right Tool

asyncio.gather(..., return_exceptions=True) is sometimes useful when you want all tasks to finish and then inspect every result or failure. That is not the same as fail-fast cancellation.

If your goal is “shut everything down when one task fails,” use TaskGroup or explicit cancellation, not a blanket “turn exceptions into results” approach.

Common Pitfalls

A common mistake is cancelling sibling tasks but never awaiting them afterward. That can leave warnings about unfinished tasks or hide cleanup errors.

Another mistake is catching CancelledError and not re-raising it. That breaks normal cancellation semantics.

Developers also overuse return_exceptions=True when they actually want fail-fast behavior. It changes the control flow and can hide failure signals.

Finally, do not assume every background task should be cancelled on first failure. Some systems want graceful degradation instead. Choose fail-fast behavior intentionally.

Summary

• On Python 3.11 and later, use asyncio.TaskGroup for fail-fast task management.
• In older code, create tasks manually, catch the exception, cancel the others, and await their cancellation.
• Always make long-running tasks cancellation-friendly.
• 'return_exceptions=True is for result collection, not for clean fail-fast shutdown.'
• The key idea is not just cancelling tasks, but cancelling them and waiting for shutdown to complete properly.