deniz.in

Markets

Weather

Loading weather

· via dev.to (home feed)

FastAPI 0.163's max_concurrency cap can deadlock routes sharing two limited dependencies

A dev.to stress test of FastAPI 0.163's new per-dependency max_concurrency option found an easy-to-trigger deadlock, plus per-route and per-worker limits that quietly multiply your configured cap.

FastAPI 0.163's max_concurrency cap can deadlock routes sharing two limited dependencies

FastAPI 0.163.0, released on 14 November 2026, shipped with a single new feature: a per-dependency concurrency cap, expressed as Depends(dependency, max_concurrency=N). A developer who spent the morning trying to break the release, writing on dev.to, reports that the cap works as documented but hides several traps — including a classic lock-ordering deadlock that hangs two routes indefinitely. The testing was done on 0.163.2, a patch issued three days after the initial release.

How the cap behaves

The option places a semaphore around a dependency. Calls beyond the limit queue up rather than run immediately. In the author's benchmark, 20 concurrent requests hitting a dependency that sleeps for 0.2 seconds completed in about 0.206 seconds with no cap, and in about 0.829 seconds with max_concurrency=5 — close to four sequential waves of five, which is exactly what a gate of five produces. Dependencies defined with def instead of async def are capped the same way: the semaphore is grabbed before the call is dispatched to the thread pool, so the cap holds even though the pool itself would run everything at once.

Every Depends() call is a separate gate

The biggest surprise for real codebases is that the limit attaches to the Depends() declaration, not to the dependency function. Writing Depends(slow_dep, max_concurrency=5) inline on two routes creates two independent semaphores; in the author's test, ten calls ran concurrently across two routes that each looked capped at five. The only way to get one shared limit is to build the Depends() object once — for example via an Annotated alias — and import it everywhere the cap should apply. As the author puts it, inline limits on every route touching a database pool don't cap the pool; the ceiling scales with your route count.

The limit is per worker process

According to the post, the documentation notes that each worker process maintains its own limit independently. Running uvicorn with two workers and max_concurrency=4, the author measured a combined peak of 8 concurrent calls, because each process holds its own semaphore and knows nothing about the other. A limit of 4 across 4 workers is effectively 16 against an external shared resource such as a remote connection pool. The test also showed an uneven 16-versus-4 split of requests between workers, though that is uvicorn behaviour rather than something this release introduced.

The deadlock

The headline hazard involves two generator dependencies — generators hold their slot for the lifetime of the request, not just the moment the function runs — each capped at max_concurrency=1. One route declares dependency A then B; the other declares B then A. Fire one request at each simultaneously and both grab their first resource within ten milliseconds, then wait forever for the second. The author let it run for eight seconds against a timeout with no resolution, and reports there is no internal deadlock detection — in production this is simply two hung requests until something external kills the connection. The remedy is the standard one: acquire capped resources in a consistent order everywhere, or avoid capping more than one shared resource on a single request path.

Edge cases and overhead

Validation rejects 0, negative numbers, floats, strings and even True — the check requires an actual int, so the bool subclass doesn't slip through despite 1 == True in Python. Leaving the argument off applies no limit at all, and None is the only explicit opt-out. Exceptions don't leak slots: after twelve concurrent failing calls, a follow-up batch returned at full speed. When never contended, the semaphore bookkeeping added roughly 45 microseconds per call against a ~216 microsecond baseline — about a fifth more.

Why it matters

A per-dependency concurrency cap looks like a clean way to protect shared resources, but this release makes it easy to believe you have capped something when you haven't: the effective ceiling is your configured limit multiplied by the number of Depends() declarations and worker processes. Teams upgrading to FastAPI 0.163 should audit where limits are declared, centralise shared Depends objects, and check resource acquisition order across routes before relying on the feature in production. The deadlock needs only two routes to reproduce and raises no error — just requests that never return.

  • #fastapi
  • #python
  • #asyncio
  • #concurrency
  • #deadlock

Related posts