Asyncio task exception handling

Mar 25, 2024 ยท 3 min read

Asynchronous programming with asyncio in Python has many advantages, but also introduces some unique exception handling challenges. When multiple coroutines and tasks run concurrently, exceptions can occur at any time and bubble up in unexpected ways.

Proper exception handling is key to creating robust asyncio code. In this guide, I'll share tips and best practices for handling exceptions effectively in asyncio:

The Basics: Try/Except Blocks

The fundamental tool for catching exceptions in asyncio is the trusty try/except block:

import asyncio

async def main():
    await some_risky_operation()
  except ValueError:
    print("Encountered a value error!")

This allows you to catch expected exceptions and handle them appropriately in a particular coroutine.

However, exceptions in asyncio can surface in other tasks or the event loop. So try/except is not enough on its own.

Handle Exceptions at the Top Level

It's best practice in asyncio to use a top-level exception handler that will catch any unhandled exceptions across all tasks:

import asyncio

async def main():
    task1 = asyncio.create_task(foo()) 
    task2 = asyncio.create_task(bar())
    await asyncio.gather(task1, task2) 
  except Exception:
    print("Encountered an unhandled exception") 

The function will automatically surface uncaught exceptions. But explicitly handling the top level with try/except ensures you can respond appropriately.

Log Exceptions to Diagnose Problems

Bubbling exceptions lose their tracebacks, making the root cause hard to diagnose.

To address this, log exceptions as they occur:

import asyncio
import logging

async def foo():
  except Exception:
    logging.exception("Exception in foo")


This preserves the full traceback for diagnostics.

Cancel Tasks on Exception

It's often prudent to cancel all sibling tasks when one fails:

async def main():
    task1 = asyncio.create_task(foo())
    task2 = asyncio.create_task(bar())

    await asyncio.gather(task1, task2))
  except Exception:
    print("Canceled all tasks")

This minimizes follow-on errors and cleans up processing.


  • Use top-level exception handling to catch unhandled errors
  • Log exceptions with tracebacks for diagnostics
  • Cancel outstanding tasks on failure to contain damage
  • With these tips, you can make your asyncio code resilient to exceptions and easier to troubleshoot when things go wrong!

    The key is laying defensive exception handling at each level: catching exceptions early at the operation level, handling uncaught exceptions globally, logging tracebacks, and canceling damaged tasks.

    Asyncio introduces unique exception propagation challenges. But with careful handling, you can isolate failures and maintain robust asynchronous systems.

    Browse by tags:

    Browse by language:

    The easiest way to do Web Scraping

    Get HTML from any page with a simple API call. We handle proxy rotation, browser identities, automatic retries, CAPTCHAs, JavaScript rendering, etc automatically for you

    Try ProxiesAPI for free

    curl ""

    <!doctype html>
        <title>Example Domain</title>
        <meta charset="utf-8" />
        <meta http-equiv="Content-type" content="text/html; charset=utf-8" />
        <meta name="viewport" content="width=device-width, initial-scale=1" />


    Don't leave just yet!

    Enter your email below to claim your free API key: