What causes "No route exists for name "{name}" and params "{params}"." in tiangolo/fastapi?

Verify the name exists on a path operation: `@app.get('/items/{id}', name='get_item')`.

tiangolo/fastapi · error · NoMatchFound

No route exists for name "{name}" and params "{params}".

Error message

No route exists for name "{name}" and params "{params}".

What it means

`_FrontendRoute.url_path_for` (fastapi/routing.py:2100) always raises `NoMatchFound(name, path_params)`. Frontend static routes are not named and do not support reverse URL generation. During URL reversal (`app.url_path_for` / `request.url_for`), FastAPI iterates all routes and asks each to resolve the name; a frontend route answering NoMatchFound means 'I don't match, try the next'. The user only sees this propagate if NO route matches the requested name.

Source

Thrown at fastapi/routing.py:2100

            return Match.PARTIAL, child_scope
        return Match.FULL, child_scope

    def _get_frontend_path(self, path: str, route_path: str) -> str | None:
        if path == "/":
            return route_path.lstrip("/")
        if route_path == path:
            return ""
        prefix = path + "/"
        if route_path.startswith(prefix):
            return route_path[len(prefix) :]
        return None

    async def handle(self, scope: Scope, receive: Receive, send: Send) -> None:
        response = await self.app.get_response_for_scope(scope)
        await response(scope, receive, send)

    def url_path_for(self, name: str, /, **path_params: Any) -> URLPath:
        raise NoMatchFound(name, path_params)


class _FrontendRouteGroup(BaseRoute):
    def __init__(
        self,
        *,
        dependencies: Sequence[params.Depends] | None = None,
        dependency_overrides_provider: Any | None = None,
    ) -> None:
        self.routes: list[_FrontendRoute] = []
        self.dependencies = list(dependencies or [])
        self.dependency_overrides_provider = dependency_overrides_provider
        (
            self.dependant,
            _,
            self._embed_body_fields,
        ) = _build_dependant_with_parameterless_dependencies(
            path="",

View on GitHub (pinned to 3e8d1526d8)

Solutions

Verify the name exists on a path operation: `@app.get('/items/{id}', name='get_item')`.
Use the exact `name` (default is the endpoint function's `__name__`).
Search the codebase for `name='...'` to confirm the registered name before calling `url_path_for`.

Example fix

// before
url = request.url_for('getitem', id=5)  # wrong name
// after
@app.get('/items/{id}', name='getitem')
async def getitem(id: int): ...
url = request.url_for('getitem', id=5)

Defensive patterns

Strategy: validation

Validate before calling

from fastapi.routing import compile_path

def route_name_exists(app, name: str) -> bool:
    return any(getattr(r, 'name', None) == name for r in app.routes)

if not route_name_exists(app, 'get_item'):
    raise ValueError('no route named get_item; fix the name before url_path_for')
url = app.url_path_for('get_item', id=5)

Type guard

def is_known_route_name(app, name: object) -> bool:
    return isinstance(name, str) and any(getattr(r, 'name', None) == name for r in app.routes)

Try / catch

from fastapi.exceptions import NoMatchFound

try:
    url = app.url_path_for('maybe_name', id=5)
except NoMatchFound:
    url = None  # graceful fallback

Prevention

Define route names as module constants and reuse them at lookup sites.
Add a startup test asserting every url_path_for call resolves.
Avoid reversing against the default function name; set explicit name=.

When it happens

Trigger: Calling `app.url_path_for('nonexistent')` or `request.url_for('typo_name', **params)` where no registered path operation has that `name`. The frontend route participates in the search and declines via NoMatchFound, but the final raised exception originates from the last route (often a frontend route) that was tried.

Common situations: Renaming a path operation without updating calls to `url_path_for`. Using a name that was never set (default name is the function name). Typo in the name string. Calling `url_for` from a template with stale names after refactoring.

Related errors

AI-assisted analysis of tiangolo/fastapi@3e8d1526d8 (2026-08-11). Data as JSON: /api/errors/dde7f394cd9ccec4. Report an issue: GitHub.