Signal a missing resource
A route loader cannot retrieve a post, user, or other resource by identifier.
TanStack · Function
notFound
Creates a TanStack Router not-found error for missing resources or route handling. Return it or throw it from beforeLoad or loader callbacks, with options available to select handling and control throwing.
How it works
Call notFound to create a TanStack Router not-found error. Throw it from a route loader or beforeLoad callback when a resource is absent; alternatively, configure options such as routeId, data, or throw to control handling and whether the function throws immediately.
Syntax
notFound(options?)Parameters
| Name | Type | Description |
|---|---|---|
options | NotFoundErrorOptions | Optional configuration for the not-found error, including throw, routeId, and data. |
Returns
A NotFoundError object by default; with options.throw set to true, the function throws the object instead.
Key points
- notFound constructs the error representation used by TanStack Router for missing resources.
- Use it in route lifecycle callbacks to signal that required data is unavailable.
- Its API takes one optional options object.
Common mistakes
- By default, notFound returns an error object; use throw: true when the call itself must throw it.
Example: Throw from a route loader
import { notFound, createFileRoute } from '@tanstack/react-router'
export const Route = createFileRoute('/posts/$postId')({
loader: async ({ params }) => {
const post = await getPost(params.postId)
if (!post) throw notFound()
return post
},
})
async function getPost(id: string) {
return id === '1' ? { id, title: 'Hello' } : undefined
}The loader throws a not-found error when the requested post does not exist.
When to use it
Force immediate throwing
A helper needs to throw immediately rather than return an error object.
Select the handling route
A specific route or the root route should render the not-found UI.
Interview questions
QWhat does notFound do?
notFound creates a NotFoundError that can be returned or thrown from route beforeLoad and loader callbacks. Throwing it signals TanStack Router to render the applicable notFoundComponent.
Follow-up: How can the root route handle the error? Use routeId for the root route, or configure the router's notFoundMode as root so root handling is selected.
QHow does the throw option change behavior?
Calling notFound() returns the error object by default. Passing { throw: true } makes the function throw the object instead, which is useful when a throwing helper should have a never-like control flow.
Follow-up: What happens when throw is false or omitted? The object is returned and must be thrown by the caller if it should trigger not-found handling.
QWhat is routeId used for?
The optional routeId identifies the route that should attempt to handle the error. If that route has no notFoundComponent, the error can bubble to a parent, eventually reaching the root when needed.
Follow-up: What is the default handling route? TanStack Router normally tries the route that threw the error, while notFoundMode can change route-matching behavior.
Related
NotFoundErrornotFoundComponentNot Found ErrorsRouterOptions