skip to content

In FastAPI, when middleware is registered with both app.add_middleware and @app.middleware("http"), which runs first, and where do the built-in layers sit?

level: middleimportance: should knowfreq 35%

answer

  1. one stack for both styles
  2. insert at the front
  3. last added is outermost
  4. error layers bracket your middleware
  5. built on the first request

basics

~20 s

Both styles feed one stack, and each new registration becomes the outermost layer, so the last one added runs first on the request and last on the response. ServerErrorMiddleware wraps all of them; ExceptionMiddleware sits inside them.

solid answer

~30 s

`@app.middleware("http")` is a shortcut for `app.add_middleware(BaseHTTPMiddleware, dispatch=func)`, and `add_middleware` inserts at index 0 of `app.user_middleware`. So after `add_middleware(A)` then `add_middleware(B)`, a request goes B, then A, then the route, and the response comes back A, then B. Entries passed as `FastAPI(middleware=[...])` keep list order, first outermost, and anything added later wraps them. The stack is built on the app's first call: `ServerErrorMiddleware` outermost, then your middleware, then `ExceptionMiddleware` (which runs `exception_handler`s for `HTTPException` and friends), then the router. Calling `add_middleware` after that raises `RuntimeError`. In FastAPI 0.143 middleware belongs to the app; `APIRouter` has no `add_middleware`.

code

python · 38 lines
python
from collections.abc import Awaitable, Callable

from fastapi import FastAPI, Request, Response
from fastapi.middleware import Middleware
from starlette.types import ASGIApp, Receive, Scope, Send

seen: list[str] = []


class Tag:
    def __init__(self, app: ASGIApp, name: str) -> None:
        self.app = app
        self.name = name

    async def __call__(self, scope: Scope, receive: Receive, send: Send) -> None:
        if scope["type"] == "http":
            seen.append(self.name)
        await self.app(scope, receive, send)


# Constructor list: kept in order, first entry outermost of the two
app = FastAPI(middleware=[Middleware(Tag, name="init-1"), Middleware(Tag, name="init-2")])

app.add_middleware(Tag, name="added-A")
app.add_middleware(Tag, name="added-B")  # wraps added-A


@app.middleware("http")  # registered last, so outermost of all user middleware
async def decorator(
    request: Request, call_next: Callable[[Request], Awaitable[Response]]
) -> Response:
    seen.append("decorator")
    return await call_next(request)


@app.get("/")
async def root() -> dict[str, list[str]]:
    return {"seen": seen}

go deeper

for a junior

Remember the one rule: the last middleware you add is the outermost, so it sees the request first and the response last.

for a middle

Explain insert(0) into app.user_middleware, the decorator delegating to add_middleware, and ServerErrorMiddleware outside versus ExceptionMiddleware inside your layers.

for a senior

Use the layout to predict behaviour: which exceptions your middleware sees, why its own raise becomes a 500, and why CORSMiddleware goes last.

for a principal

Set a convention for where middleware is registered, one module at app creation, so ordering stays reviewable instead of depending on import order.

## One stack, two ways in FastAPI gives you two ways to register middleware, and they end up in the same list: - **`app.add_middleware(SomeMiddleware, **options)`** stores `Middleware(SomeMiddleware, **options)` in `app.user_middleware`. - **`@app.middleware("http")`** is a shortcut: its decorator calls `self.add_middleware(BaseHTTPMiddleware, dispatch=func)`. Because the decorator delegates to `add_middleware`, mixing the two styles changes nothing about ordering; only the sequence of registration matters. A third way, `FastAPI(middleware=[Middleware(A), Middleware(B)])`, sets the initial list in the constructor. ## Last added is outermost Starlette's `add_middleware` does `self.user_middleware.insert(0, Middleware(...))`: every new registration goes to the **front** of the list. When the stack is built, the list is wrapped from the inside out, so the front of the list becomes the **outermost** layer. The FastAPI docs put it this way: ```python app.add_middleware(MiddlewareA) app.add_middleware(MiddlewareB) # Request: MiddlewareB -> MiddlewareA -> route # Response: route -> MiddlewareA -> MiddlewareB ``` The constructor list behaves the other way round: `FastAPI(middleware=[Middleware(A), Middleware(B)])` keeps the list as written, so `A` is outer to `B`. Anything you add later with `add_middleware` or the decorator wraps both. ## The full stack in FastAPI 0.143 `FastAPI.build_middleware_stack()` overrides Starlette's version and assembles, from outside in: | Layer | Role | |---|---| | `ServerErrorMiddleware` | catches any unhandled exception and returns a 500; runs a handler registered for `Exception` or `500` | | your middleware | last added first | | `ExceptionMiddleware` | runs `exception_handler`s for `HTTPException`, `RequestValidationError` and other registered types | | `AsyncExitStackMiddleware` | FastAPI's own layer, used to close uploaded files | | the router | matches the path and runs dependencies and the path operation | (FastAPI 0.143 also places an internal telemetry layer just inside `ServerErrorMiddleware`; it does not change where your middleware sits.) Two consequences follow directly from this layout: 1. An `HTTPException` raised inside a path operation is turned into a response by `ExceptionMiddleware`, **inside** your middleware, so your middleware sees an ordinary response. 2. An exception raised **by your middleware itself** never reaches `ExceptionMiddleware`; it propagates out to `ServerErrorMiddleware` and becomes a 500. 3. A `RequestValidationError` is also handled inside, so your middleware sees the finished 422 response, not the exception object. 4. A sub-application mounted with `app.mount()` is reached through the router, so the parent's middleware wraps it too; middleware added to the sub-application applies only to it. ## When the stack is built The stack is built lazily, on the first call to the app (the first request, or the lifespan startup the server sends first). Middleware classes are instantiated **once**, at that moment, and the instances serve every later request. After that point Starlette refuses changes: `app.add_middleware(...)` raises `RuntimeError("Cannot add middleware after an application has started")`. Register everything at import time, next to where the app is created. ## Scope: the app, not a router In FastAPI 0.143 middleware is application-wide. `APIRouter` has no `add_middleware` or `middleware` method; the 0.137 release notes list "middleware per router" only as a future feature that the router refactor makes possible. To limit middleware to some paths you check `request.url.path` (or the ASGI scope) inside it, or mount a separate sub-application that has its own middleware. ## Reading the stack while debugging `app.user_middleware` is the list FastAPI will wrap, already in outermost-first order. Printing `[m.cls.__name__ for m in app.user_middleware]` after all registrations shows the order a request will take; a decorated function appears as `BaseHTTPMiddleware`. When registrations are spread over several modules, this one line settles which layer really runs first, instead of reasoning about import order. ## Practical ordering rules in FastAPI - Add `CORSMiddleware` **last** so it is outermost: it then answers preflight requests before any other middleware runs, and adds CORS headers to whatever the inner layers return. - Add `TrustedHostMiddleware` late as well, so a request with a forged host is refused before other middleware spends work on it. - Put a timing or logging middleware outside the ones whose cost you want to include in the measurement. - Remember that nothing you add can sit outside `ServerErrorMiddleware`, so its 500 responses never pass through your middleware.

  • Why does FastAPI raise RuntimeError when add_middleware is called inside a path operation?
    The middleware stack is assembled and every middleware class instantiated on the app's first call, and the request being served already runs through that stack. Starlette's `add_middleware` checks that `middleware_stack` is still unset and otherwise raises `RuntimeError("Cannot add middleware after an application has started")`. The built stack is cached on the app and never rebuilt, so registration has to happen at import time.
  • In FastAPI, how do you apply a middleware to only the routes under /admin?
    Middleware is app-wide in FastAPI 0.143, so either check the path inside it (`if request.url.path.startswith("/admin")`, or `scope["path"]` in a pure ASGI class) and pass other requests straight to the next layer, or build a separate `FastAPI()` sub-application with its own middleware and `app.mount("/admin", sub_app)`. Per-route behaviour such as authentication usually belongs in a router-level dependency instead.

  • Says middleware runs in the order it was added, first added first.
  • Thinks @app.middleware and add_middleware keep two separate stacks.
  • Believes middleware can be added at any time, even after startup.
  • Expects APIRouter to accept its own add_middleware in FastAPI 0.143.
  • Places user middleware outside ServerErrorMiddleware.

Assumes FastAPI 0.143, where middleware attaches only to the application; the 0.137 release notes list per-router middleware as a future feature.