Repository navigation
Description
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
- Decorate an
async deffunction with@circuit_breaker(failure_threshold=1). - Inside the async function, raise an exception qualifying as a failure.
- Call and
awaitthe decorated function. - Catch the exception and check the circuit breaker state. The circuit remains in
CLOSEDstate.
Powertools for AWS Lambda (Python) version
latest
AWS Lambda function runtime
3.12
Packaging format used
PyPi
Metadata
Metadata
Assignees
Labels
Type
Projects
- StatusShow more project fieldsComing soon
Activity
ASHMEET555 commentedon Oct 28, 2026
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(viainspect.iscoroutinefunction) and add regression tests. Would love your guidance before opening a PR!leandrodamascena commentedon Oct 29, 2026
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:
CircuitStatelives incircuit_breaker.states, nottypes, and the decorator needs apersistence_store. The fix is an async-aware wrapper, detectiscoroutinefunctionand 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.powertools-for-aws-oss-automation commentedon Oct 29, 2026
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.
github-actions commentedon Nov 3, 2026
This is now released under 3.39.0 version!