Two routes in my test app each took one dependency that managed a shared resource, each capped to one concurrent user with FastAPI's new max_concurrency option. One route asked for resource A then resource B. The other asked for B then A. I fired one request at each at the same time and neither ever came back. Not slow — I let it run for eight seconds and it would have sat there forever.

FastAPI 0.163.0 shipped on 14 November 2026 with a single feature: Depends(dependency, max_concurrency=N), a per-dependency concurrency cap. I installed it the day it reached PyPI (I'm on 0.163.2, released three days later) and spent the morning trying to break it rather than just read the one new paragraph in the docs.

What it actually does

max_concurrency wraps a dependency in a semaphore. Call the dependency more times at once than the limit allows and the extra calls wait, without a worker thread or an event loop task stuck doing nothing useful.

I built a FastAPI app with one async dependency that sleeps for 0.2 seconds, and fired 20 requests at it concurrently through httpx.AsyncClient talking straight to the ASGI app (no network, so the numbers are the dependency's own concurrency, not socket noise):

async def slow_dep(): await asyncio.sleep(0.2) @app.get("/work") async def work(_=Depends(slow_dep, max_concurrency=5)): return {"ok": True} 
peak concurrent calls wall time for 20 requests
no limit 20 0.206s
max_concurrency=5 5 0.829s

0.829s is almost exactly four batches of 0.2s — 20 requests through a gate of 5 queue up in four waves. I reran it three times and the wall time never moved outside 0.82–0.84s. The cap does what it says.

Sync (def, not async def) dependencies behave the same way. FastAPI runs those in a thread pool, and the semaphore is acquired before the call is handed to the pool, not after — so a sync dependency with max_concurrency=5 also peaked at 5 concurrent threads against the same 20 requests, in the same ~0.83s, even though Starlette's own thread pool would happily have run all 20 at once.

The limit belongs to the Depends() call, not the function

The docs say this directly, in one line I'd have skipped on a first read: "A new Depends() object creates a separate limit, even for the same dependency function." I wanted the number behind that sentence.

I put the same dependency, the same max_concurrency=5, on two different routes, written identically:

@app.get("/a") async def route_a(_=Depends(slow_dep, max_concurrency=5)): ... @app.get("/b") async def route_b(_=Depends(slow_dep, max_concurrency=5)): ... 

Fired 10 concurrent requests at each route at once, 20 total:

peak concurrent calls across both routes wall time
separate Depends() per route 10 0.418s
one Depends() object shared via an Annotated alias 5 0.829s

Ten, not five. Typing the identical call twice gives you two independent gates of five, not one shared gate of five. The only way to get one gate is to build the Depends() object once and reuse that object — assign it to a variable or an Annotated alias and import it everywhere the limit needs to apply. If you're capping something like database connections and you put the limit inline on every route that touches the database, you haven't capped anything; you've multiplied your limit by the number of routes.

What it refuses

max_concurrency=0 -> ValueError: max_concurrency must be a positive integer or None max_concurrency=-1 -> ValueError: max_concurrency must be a positive integer or None max_concurrency=2.5 -> ValueError: max_concurrency must be a positive integer or None max_concurrency="5" -> ValueError: max_concurrency must be a positive integer or None max_concurrency=True -> ValueError: max_concurrency must be a positive integer or None 

The last one surprised me. True equals 1 in Python and would be a perfectly sensible limit, but the check is type(self.max_concurrency) is not int, and type(True) is bool, not int. FastAPI rejects it even though bool is a subclass of int and 1 == True. max_concurrency=None is the only way to opt out, and it's also the default — leaving the argument off applies no limit at all, silently.

It's a per-process limit, not a per-app one

The docs flag this too: "Each worker process applies its own limit." I ran it under uvicorn --workers 2 with max_concurrency=4 and fired 20 real HTTP requests at a real socket, logging start and end times from both worker processes to one file so I could see the actual combined overlap:

requests=20 distinct worker pids hit=2 per-pid counts={1078: 16, 1077: 4} peak concurrency across all workers=8 

Eight, against a configured limit of four, because each of the two worker processes runs its own Python interpreter with its own semaphore and has no idea the other exists. If the resource you're protecting is external and shared across workers — a connection pool on a database server, say — a limit of 4 with 4 workers is actually a limit of 16. I also noticed uvicorn didn't split the 20 requests evenly between workers (16 against 4), which is its own small surprise, but not one this release is responsible for.

Failures don't leak the slot

I made a dependency that always raises, capped it at 3, and fired 12 concurrent requests at it. All 12 raised, as expected. I then immediately fired 3 more at the same capped, still-failing dependency, worried that a slot might stay held by a coroutine that exited through an exception rather than a normal return. They came back in 0.052 seconds — roughly one dependency timeout's worth of time, for all three run in parallel. No leak, no growing queue of permanently stuck slots.

The deadlock

Back to the opening. Two dependencies, A and B, both yield generators (so FastAPI holds their slot for the lifetime of the request, not just the moment the function runs), both capped at max_concurrency=1:

@app.get("/ab") async def route_ab(a=Depends(resource_a, max_concurrency=1), b=Depends(resource_b, max_concurrency=1)): ... @app.get("/ba") async def route_ba(b=Depends(resource_b, max_concurrency=1), a=Depends(resource_a, max_concurrency=1)): ... 

Fire one request at /ab and one at /ba at the same moment. /ab grabs A, /ba grabs B — both within 10 milliseconds of each other. Then /ab waits for B, which /ba is holding, and /ba waits for A, which /ab is holding. Neither releases until it gets the other. I let it run for eight seconds against a timeout and it never resolved; there's no internal deadlock detection, so in production this is just two hung requests (and, depending on your server's own timeout settings, two threads or tasks stuck until something external kills the connection).

This is exactly the scenario FastAPI's own docs point to from a "dependencies that need more than one resource" link, without spelling out that it's a real, two-line-reproducible deadlock. If two of your routes need the same two capped resources, acquire them in the same order everywhere, or don't cap more than one shared resource per request path.

What it costs when nothing is waiting

I set max_concurrency=1000 — a number nothing in the test would ever reach — and timed 3000 cheap no-op dependency calls, batched 50 at a time, against the same calls with no limit at all:

time per call (median of 3 runs)
no limit ~216µs
max_concurrency=1000, never contended ~264µs

About 45 microseconds, or roughly a fifth more, added to every call just for the semaphore bookkeeping, even when it's never actually limiting anything. Trivial for a database call, possibly worth knowing if you're tempted to wrap something that already runs in single-digit microseconds.

Watching it from outside

There's no public metric for how full a max_concurrency gate is. There's also nothing stopping you from reading one: the limit lives on the Depends() object as a private _concurrency attribute, which exposes an AnyIO Semaphore through .get_semaphore(). .value gives the free slots, .statistics().tasks_waiting gives the queue depth:

before load: free_slots=3 tasks_waiting=0 mid-load, 6 requests: free_slots=0 tasks_waiting=3 

It's a private attribute with no compatibility guarantee, so I wouldn't ship a dashboard built on it without accepting it might break on the next FastAPI release. For local debugging during a load test, it told me exactly what I wanted to know.

What I got wrong on the way

My first version of the "do failures leak a slot" test fired the follow-up requests at a different, healthy dependency instead of the same failing one. It would have reported success even if the failing dependency's own semaphore was stuck forever, because I'd have been checking a resource with no connection to the bug I was looking for. I caught it rereading the script before running it, not after a wrong result — but it's the kind of mistake that produces a clean, convincing, entirely wrong "no leak found".

Run it yourself

python3 -m venv venv && venv/bin/pip install "fastapi==0.163.2" "uvicorn[standard]" httpx 
# save as app.py, then: venv/bin/python -m uvicorn app:app # (one worker — two workers would give each its own semaphore and hide the bug) import asyncio from fastapi import FastAPI, Depends async def resource_a(): await asyncio.sleep(0.2) # stands in for a real connect/setup cost yield "A" async def resource_b(): await asyncio.sleep(0.2) yield "B" app = FastAPI() ADep = Depends(resource_a, max_concurrency=1) BDep = Depends(resource_b, max_concurrency=1) @app.get("/ab") async def route_ab(a=ADep, b=BDep): return {"a": a, "b": b} @app.get("/ba") async def route_ba(b=BDep, a=ADep): return {"a": a, "b": b} 

Hit /ab and /ba at the same time with two terminals and curl, and watch neither one come back. I confirmed this over a real socket, not just in-process: both curl calls hit a 6-second timeout and exited with code 124. Without the 0.2-second delay in the two dependencies, the race window is too narrow for two separate curl processes to land inside it — the deadlock needs genuine overlap, not just an unlucky request order.

What to do with this

Before I'd add this to anything touching a real connection pool, I'd go back through every route that uses it and grep for Depends( on that dependency. Two or more hits means two or more limits, not one — I'd pull it into a single module-level object and import that, the way the DBDep example in FastAPI's own docs already does, and I'd have missed why that example bothers with a named alias if I hadn't broken it myself first.

The worker-count division matters just as much and is easy to miss because nothing in the API warns you at the point you set the number: four workers turns max_concurrency=5 into a real ceiling of twenty on whatever's on the other side.

The one I'd actually lose sleep over is the opposite-order deadlock, because it doesn't show up in a code review and it doesn't show up with one user testing the happy path. It shows up the first time two requests touching the same two resources land close enough together in production, and from the outside it looks like the server hung for no reason. If a route needs two capped resources, I'd write down the acquisition order once, for every route, before shipping any of them.