skip to content

After a refactor, a FastAPI rate-limit dependency declared on an APIRouter and again inside a permission sub-dependency counts every request twice; what causes it, and how do you fix it?

level: seniorimportance: should knowfreq 30%

answer

  1. what the cache is keyed by
  2. two objects that look identical
  3. identity, not configuration
  4. one shared instance or alias

basics

~20 s

FastAPI's per-request cache is keyed by the dependable object, and each RateLimiter(limit=10) expression builds a different instance, so the two declarations never share an entry and both run. Create one instance and reuse it, ideally through an Annotated alias.

solid answer

~30 s

FastAPI dedupes a dependency within a request by looking up the dependable object in a per-request dictionary. Writing `Depends(RateLimiter(limit=10))` on the router and again in `require_member` creates two separate instances; a plain class compares and hashes by identity, so the keys differ, both instances run, and the counter moves twice. Two `functools.partial(...)` objects (accepted as dependables since FastAPI 0.123.5) behave the same way, and so does a stray `use_cache=False`. The fix is one module-level instance, `search_limiter = RateLimiter(limit=10)`, reused everywhere, ideally as `SearchLimit = Annotated[None, Depends(search_limiter)]`. Confirm it with a test that counts calls per request.

code

python · 31 lines
python
from typing import Annotated

from fastapi import APIRouter, Depends, FastAPI
from fastapi.testclient import TestClient

hits: list[str] = []


class RateLimiter:
    def __init__(self, limit: int):
        self.limit = limit

    def __call__(self) -> None:
        hits.append(f"counted id={id(self)}")


def require_member(_: Annotated[None, Depends(RateLimiter(limit=10))]) -> None:
    pass


router = APIRouter(dependencies=[Depends(RateLimiter(limit=10))])


@router.get("/search", dependencies=[Depends(require_member)])
def search():
    return {"hits": len(hits)}


app = FastAPI()
app.include_router(router)
print(TestClient(app).get("/search").json())

go deeper

for a junior

Recall that FastAPI runs a repeated dependency once per request only when the exact same callable object is declared each time.

for a middle

Explain that the cache is a dictionary keyed by the dependable object, so equality and hashing decide whether two declarations share a result.

for a senior

Diagnose double execution from identity, partials or use_cache=False, prove it with a call-counting test, and fix it with one shared instance behind an alias.

for a principal

Make module-level dependables and shared aliases the team convention for side-effecting dependencies, so correctness never rests on reviewers spotting identical constructors.

## The symptom A search API has a configurable limiter built from a class with `__call__`. Before the refactor it was declared once. Afterwards it appears in two places: ```python router = APIRouter(dependencies=[Depends(RateLimiter(limit=10))]) def require_member(_: Annotated[None, Depends(RateLimiter(limit=10))]): ... ``` Clients start getting rate-limited at half the expected volume, and a log line in `__call__` fires twice per request with two different `id(self)` values. Code review missed it because the two declarations look identical. ## Why the cache did not dedupe them Within one request FastAPI keeps a **dependency cache**: a dictionary whose key is built from the dependable object passed to `Depends` (plus any security scopes its subtree uses and a yield dependency's `scope`). A second declaration reuses the stored result only when it produces an **equal key**. Python dictionaries compare keys with `__hash__` and `__eq__`. For a plain class that defines neither, both come from `object`, which means **identity**: two instances are different keys however their attributes match. Each `RateLimiter(limit=10)` expression runs `__init__` and returns a new object, so: 1. The router-level declaration resolves first with instance A and stores A's result. 2. `require_member`'s declaration looks up instance B, finds nothing, and calls B. 3. The counter, keyed by client rather than by instance, moves twice. ## Other ways to get the same double run | Cause | Why the keys differ or the cache is skipped | |---|---| | Two separately created instances | identity-based equality on a plain class | | Two `functools.partial(check, limit=10)` expressions | each `partial` is a distinct object; FastAPI accepts partials as dependables since 0.123.5 | | A lambda or closure created per declaration | a new function object each time | | `Depends(limiter, use_cache=False)` on one declaration | that declaration ignores the cached value and calls again | By contrast, `Depends(get_current_user)` written in many places dedupes fine, because a module-level function is a single object. ## The fix The robust fix is to create the dependable **once** and give it a name: ```python search_limiter = RateLimiter(limit=10) SearchLimit = Annotated[None, Depends(search_limiter)] ``` Use `Depends(search_limiter)` in the router's list and `SearchLimit` in `require_member`. Both declarations now carry the same object, the second hits the cache, and the counter moves once. A named alias also prevents the next refactor from reintroducing an inline constructor. Alternatives, with their costs: - **Value equality**: making the class a `@dataclass(frozen=True)` gives it `__eq__` and `__hash__` by field value, so two `RateLimiter(limit=10)` instances become equal keys and dedupe. It works, but it couples correctness to a property readers rarely check. A non-frozen `@dataclass` is worse: its `__hash__` is `None`, and FastAPI fails the request with `TypeError: unhashable type` when it builds the cache key. - **Declare it in one place only**: correct, but fragile when another dependency later needs the limiter. ## Proving it A regression test is cheap with `fastapi.testclient.TestClient`: give the limiter a call counter, make one request, assert exactly one call. The example's broken version prints `{'hits': 2}`; the fixed version prints `{'hits': 1}`. For production diagnosis, log `id(self)` inside `__call__`; two different ids in one request means two dependables, while the same id twice means `use_cache=False` somewhere. ## Why the refactor introduced it Before the refactor the limiter was declared once, so the identity question never came up. Two common refactors create the second declaration: 1. Moving a check from each endpoint to the router, while a permission dependency written earlier still declares it too. 2. Extracting a permission dependency that "also needs the limiter", copied with its inline constructor from an endpoint. Neither change looks wrong in a diff, and both pass functional tests, because each request still succeeds. Only the side effect doubles. That is why side-effecting dependencies (quotas, rate counters, audit writes) deserve a test that counts calls, while pure ones (parsing a header, reading paging) are harmless when they run twice. ## Takeaways - The cache dedupes by **object**, not by class, name or configuration. - Build parameterised dependables once, at module level, and share them through an `Annotated` alias. - Treat inline `Depends(SomeClass(...))` or `Depends(partial(...))` repeated across a tree as a review flag.

  • In FastAPI, would declaring Depends(RateLimiter) (the class) in both places also run twice per request?
    No. The class object is a single module-level object, so both declarations produce the same cache key and the second reuses the first instance. But that form makes FastAPI read `__init__`, so `limit` becomes a client-supplied query parameter, which is a worse bug than the double count.
  • In FastAPI, how would you tell a double run caused by use_cache=False from one caused by two instances?
    Log `id(self)` (or `id` of the function) inside the dependable. Two different ids in one request mean two distinct dependables, so two cache keys. The same id appearing twice means one dependable was called twice, which points at a declaration with `use_cache=False`.

  • Assumes FastAPI dedupes dependencies by class name or constructor arguments.
  • Fixes the double count by halving the configured limit.
  • Blames the router for running its dependencies twice per request.
  • Thinks a non-frozen dataclass instance will dedupe by field values.
  • Expects two functools.partial objects with equal arguments to share a cache entry.

Assumes FastAPI 0.143; functools.partial objects are accepted as dependables since 0.123.5, which adds partials to the ways two declarations can miss each other's cache entry.