Skip to content

Bug: @circuit_breaker decorator does not track exceptions raised by async coroutines #8697

Closed

Description

@ASHMEET555

Expected Behaviour

When @circuit_breaker wraps an asynchronous coroutine (async def), failures raised upon awaiting the coroutine should be caught and counted towards failure_threshold, transitioning the circuit from CLOSED to OPEN when the threshold is reached.

Current Behaviour

In aws_lambda_powertools/utilities/circuit_breaker/circuit_breaker.py (line 94) and aws_lambda_powertools/utilities/circuit_breaker/base.py (line 189):

The wrapper returned by the decorator is purely synchronous. When decorating an async def function, self.function(*self.fn_args, **self.fn_kwargs) executes synchronously and immediately returns a coroutine object without awaiting it.

Because returning an un-awaited coroutine succeeds synchronously without raising, the breaker treats the call as a success. When the caller awaits the coroutine, any exception occurs outside the breaker's try/except block. Consequently, failures are never counted, and the circuit stays CLOSED.

Code snippet

import asyncio
from aws_lambda_powertools.utilities.circuit_breaker import circuit_breaker, CircuitBreakerConfig
from aws_lambda_powertools.utilities.circuit_breaker.types import CircuitState

config = CircuitBreakerConfig(failure_threshold=1)

@circuit_breaker(name="async-service", config=config)
async def failing_call():
    raise ConnectionError("Service unreachable")

async def test():
    try:
        await failing_call()
    except ConnectionError:
        pass

    # The circuit remains CLOSED because the failure happened inside the awaited coroutine
    # outside the breaker's synchronous execution wrapper.
    # Expected: CircuitState.OPEN
    # Actual: CircuitState.CLOSED

asyncio.run(test())

Possible Solution

Detect whether the decorated function is a coroutine function (e.g. using inspect.iscoroutinefunction(function)) and provide an async execution path in CircuitBreakerHandler that awaits the function inside the circuit breaker state machine (_call_closed, _call_probe, etc.), or clarify the documentation regarding async coroutine support.

Steps to Reproduce

  1. Decorate an async def function with @circuit_breaker(failure_threshold=1).
  2. Inside the async function, raise an exception qualifying as a failure.
  3. Call and await the decorated function.
  4. Catch the exception and check the circuit breaker state. The circuit remains in CLOSED state.

Powertools for AWS Lambda (Python) version

latest

AWS Lambda function runtime

3.12

Packaging format used

PyPi

Activity

  1. ASHMEET555 commented on Oct 28, 2026

    @ASHMEET555
    ContributorAuthor

    Hi @leandrodamascena , opening this for triage on whether async coroutine handling is intended for @circuit_breaker.

    If this fits the roadmap, I'm happy to draft an implementation with an async execution path in CircuitBreakerHandler (via inspect.iscoroutinefunction) and add regression tests. Would love your guidance before opening a PR!

  2. leandrodamascena commented on Oct 29, 2026

    @leandrodamascena
    Contributor

    Thanks @ASHMEET555, confirmed, and it's a good catch. With the same failing call, the sync version opens the circuit on the second call and the async version never does, because the wrapper returns the coroutine before anything is awaited. Two notes on the snippet: CircuitState lives in circuit_breaker.states, not types, and the decorator needs a persistence_store. The fix is an async-aware wrapper, detect iscoroutinefunction and await inside the try, like the Event Handler middlewares do. It's yours if you want it, one PR per issue please. This goes into 3.40.0.

  3. powertools-for-aws-oss-automation commented on Oct 29, 2026

    @powertools-for-aws-oss-automation

    Warning

    This issue is now closed. Please be mindful that future comments are hard for our team to see.
    If you need more assistance, please either reopen the issue, or open a new issue referencing this one.
    If you wish to keep having a conversation with other community members under this issue feel free to do so.

  4. github-actions commented on Nov 3, 2026

    @github-actions
    Contributor

    This is now released under 3.39.0 version!

  5. removed
    pending-releaseFix or implementation already in dev waiting to be released
    on Nov 3, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

Labels

bugSomething isn't working

Type

No type

Projects

Milestone

Relationships

None yet

Development

No branches or pull requests

Issue actions