Lifespan context manager shutdown timeout configuration

Direct answer

FastAPI does not provide a native mechanism to enforce a hard timeout on the lifespan shutdown sequence. The code after yield in a lifespan context manager runs until it finishes. To prevent cleanup from exceeding the ASGI server's grace period, you must add your own timeout inside the lifespan block and align it with the server's shutdown window.

Confirmed behavior vs. likely cause

Confirmed by the framework's design: the lifespan protocol has no built-in deadline for the shutdown phase. Uvicorn exposes --timeout-graceful-shutdown to bound the total shutdown period; if lifespan cleanup exceeds that value, the server terminates the process. The likely explanation for orphaned resources is that the server's grace period expires before cleanup completes, or the cleanup coroutine is not cancellation-safe.

Steps for this case

1. Wrap the post-yield cleanup in asyncio.wait_for(cleanup(), timeout=N) (or anyio.fail_after(N) if you prefer AnyIO).
2. Make cleanup idempotent and ensure it handles asyncio.CancelledError so a forced cancellation does not corrupt state.
3. Set the server's graceful timeout slightly above your manual timeout. For example, if you cap cleanup at 5 seconds, configure Uvicorn with a 10-second grace period so the server waits for your bounded cleanup rather than killing the worker first.

from contextlib import asynccontextmanager
import asyncio

@asynccontextmanager
async def lifespan(app):
    yield
    try:
        await asyncio.wait_for(cleanup_resources(), timeout=5.0)
    except asyncio.TimeoutError:
        # Log and force-close critical handles
        pass

If cleanup cannot be made cancellation-safe or must always run to completion, do not add a manual timeout. Instead, raise the server's graceful-shutdown timeout above the worst-case cleanup duration, or offload long cleanup to a separate background process that outlives the ASGI worker.

Practical verification

• Check the ASGI server startup log for the graceful-shutdown timeout message to confirm the configured limit.
• Insert a deliberate await asyncio.sleep(10) in the shutdown block and observe whether the server waits the full duration or cuts off after its configured timeout.
• Monitor logs to verify that asyncio.CancelledError is raised inside your cleanup when the manual timeout expires.

One missing detail that changes the advice

Are your shutdown tasks already written to handle asyncio.CancelledError? If they are not, wrapping them in asyncio.wait_for can leave half-closed connection pools or sockets. In that case, skip the manual timeout and tune the server grace period instead.

Version assumptions: The lifespan context manager is available in FastAPI 0.93 and later. The --timeout-graceful-shutdown flag is available in current Uvicorn releases; verify your server version if behavior differs.