tiangolo/fastapi · error · NoMatchFound
No route exists for name
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.
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
- A frontend path cannot be empty
- A frontend path must start with '/'
- fallback must be 'auto', 'index.html', '404.html', or None
- Frontend directory ' ' does not exist. Resolved absolute…
- Frontend fallback file
AI-assisted analysis of tiangolo/fastapi@3e8d1526d8 (2026-08-11).
Data as JSON: /api/errors/dde7f394cd9ccec4.
Report an issue: GitHub.
Appendix: 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)