FAPI003 `router-wiring`¶

What it does¶

Opt-in. Reports three ways a FastAPI router's routes go missing without any error:

Unmounted router: an APIRouter(...) bound to a name at module level, with at least one path operation, that no app reaches through include_router or mount, directly or through other routers. Reported on the APIRouter(...) line.
Inclusion cycle: routers that include each other, directly or through others, or a router that includes itself. Each group of routers is reported once, with the whole cycle in the message, on the include_router call that closes it.
Included before its routes: in one file, parent.include_router(child) at module level runs above a @child.get(...) decorator. include_router copies the routes that exist when it runs, so the routes below it are missing.

Why is this bad¶

An agent adds app/invoices/router.py with three endpoints and tests them against the router, but never adds app.include_router(...) to main.py. The tests pass, and the endpoints don't exist. FastAPI doesn't complain about a router nobody includes, and Ruff checks one file at a time, so nothing else reports it. A cycle, or an inclusion above the routes, gives an app a route set that depends on the order the calls run in.

Example¶

pyproject.toml

[tool.inwards]
layers = [{ name = "app", modules = ["app"] }]

[tool.inwards.rules]
extend-select = ["FAPI003"]

app/main.py

from fastapi import FastAPI

from app.orders import router as orders

app = FastAPI()
app.include_router(orders.router)

app/orders/router.py

from fastapi import APIRouter

router = APIRouter(prefix="/orders", tags=["orders"])


@router.get("/{order_id}")
async def get_order(order_id: int) -> dict[str, int]:
    return {"id": order_id}

app/invoices/router.py

from fastapi import APIRouter

router = APIRouter(prefix="/invoices", tags=["invoices"])


@router.get("/{invoice_id}")
async def get_invoice(invoice_id: int) -> dict[str, int]:
    return {"id": invoice_id}

inwards check app

app/invoices/router.py:3:10: FAPI003 APIRouter `app.invoices.router.router` has path operations, but no app includes it, directly or through another router, so its routes don't exist at runtime.
  fix: Include `router` in the app or router that serves its siblings.
    1. In app/main.py, which builds the app `app`, where its sibling routers are included: import `app.invoices.router.router` and add `app.include_router(...)` for it.
    2. If it is meant to stay unmounted (a later release, a test-only router), tell the user: they can add it to allow-unmounted in [tool.inwards.rules.router-wiring], or suppress this line with a reason.
    3. Don't delete the router or its routes to make this finding go away.
  docs: https://sircypkowskyy.github.io/inwards/rules/FAPI003/

Fixed: main.py includes both routers.

app/main.py

from fastapi import FastAPI

from app.invoices import router as invoices
from app.orders import router as orders

app = FastAPI()
app.include_router(orders.router)
app.include_router(invoices.router)

inwards check app

How it works¶

FAPI003 reads the shared FastAPI model (ADR-037) and builds a graph of apps and routers from it:

Roots: every FastAPI(...) in the project, including one built inside a factory function such as create_app(). With entrypoints, only the apps it names.
Edges: each include_router and mount call. The receiver and the target are resolved across files through the imports, never by importing the app: router, invoices.router after from app import invoices, invoices_router after from app.invoices.router import router as invoices_router, a re-export in an __init__.py, and each name in a list or tuple literal that a for loop calls include_router on.
One hop of first-party code (#391). When the receiver or the target is a parameter of the module-level function the call sits in (def wire(app, api_router): app.include_router(api_router)), Inwards finds every call of that function in the project (in files that spell its name, through re-exports too) and adds one edge per call, with the names that call passes, by position, keyword or default. A function used other than by a call (hooks = [wire]) or imported under another name (from app.wiring import wire as hook), a parameter the body assigns again, a call with *args or **kwargs, or an argument that isn't a name leaves that inclusion unresolved. include_router(make_router()) includes the router make_router builds and returns (router = APIRouter(...) ... return router); a factory whose returned router can't be read stays unresolved. A mount on a parameter is followed the same way.
Receivers Inwards can't find, such as the app parameter of a register(app) function nothing calls: what they include counts as reached, since something includes it.

Files are found by a text pre-filter (fastapi, APIRouter, include_router...) and parsed once. The graph is built only when a checked file holds a router, an app or an include_router call.

Where it runs:

inwards check, inwards baseline and the Stop gate report all three kinds, but only in the files they check: a partial run checks its files against the whole project's graph. The Stop gate checks the files the session changed, so a router created or changed in the session blocks if it is still unmounted at the end, and a router that was already unmounted at session start doesn't.
The PostToolUse hook and the editor report only what one file shows: an inclusion above the routes, and a router that includes itself. Creating a router and wiring it into main.py are two edits, and blocking the first would be wrong.

The graph is also what the FastAPI rules that need an inclusion path read (#183, #224, #227): rules/fastapi/model/_graph.ts.

How to fix¶

Unmounted: include the router in the app, or in the parent router where its sibling routers are included. The fix names that module. Don't delete the router.
Cycle: remove one of the include_router calls the fix lists. Keep the one that goes from the router closer to the app down to its child.
Included before its routes: move the include_router call below the last decorator of the included router, or into the module that builds the app.

Fix safety¶

No automatic fix (autofix: false). Where a router belongs, and which inclusion of a cycle is wrong, are design decisions.

Configuration¶

Severity error. Opt-in: turn it on with extend-select. Its options go in [tool.inwards.rules.router-wiring]: