router-core/not-found-and-errors
sub-skill>-
Not Found and Errors
TanStack Router handles two categories of "not found": unmatched URL paths (automatic) and missing resources like a post that doesn't exist (manual via notFound()). Error boundaries are configured per-route via errorComponent.
CRITICAL: Do NOT use the deprecated NotFoundRoute. When present, notFound() and notFoundComponent will NOT work. Remove it and use notFoundComponent instead. CRITICAL: useLoaderData may be undefined inside notFoundComponent. Use useParams, useSearch, or useRouteContext instead.
Not Found Handling
Global 404: notFoundComponent on Root Route
// src/routes/__root.tsx
import { createRootRoute, Outlet, Link } from '@tanstack/react-router'
export const Route = createRootRoute({
component: () => <Outlet />,
notFoundComponent: () => {
return (
<div>
<h1>404 — Page Not Found</h1>
<Link to="/">Go Home</Link>
</div>
)
},
})
Router-Wide Default: defaultNotFoundComponent
// src/router.tsx
import { createRouter } from '@tanstack/react-router'
import { routeTree } from './routeTree.gen'
const router = createRouter({
routeTree,
defaultNotFoundComponent: () => {
return (
<div>
<p>Not found!</p>
<Link to="/">Go home</Link>
</div>
)
},
})
Per-Route 404: Missing Resources with notFound()
Throw notFound() in loader or beforeLoad when a resource doesn't exist. It works like redirect() — throw it to trigger the not-found boundary.
// src/routes/posts.$postId.tsx
import { createFileRoute, notFound } from '@tanstack/react-router'
import { getPost } from '../api'
export const Route = createFileRoute('/posts/$postId')({
loader: async ({ params: { postId } }) => {
const post = await getPost(postId)
if (!post) throw notFound()
return { post }
},
component: PostComponent,
notFoundComponent: ({ data }) => {
const { postId } = Route.useParams()
return <p>Post "{postId}" not found</p>
},
})
function PostComponent() {
const { post } = Route.useLoaderData()
return <h1>{post.title}</h1>
}
Targeting a Specific Route with notFound({ routeId })
You can force a specific parent route to handle the not-found error:
// src/routes/_layout/posts.$postId.tsx
import { createFileRoute, notFound } from '@tanstack/react-router'
export const Route = createFileRoute('/_layout/posts/$postId')({
loader: async ({ params: { postId } }) => {
const post = await getPost(postId)
if (!post) throw notFound({ routeId: '/_layout' })
return { post }
},
})
Targeting Root Route with rootRouteId
import { createFileRoute, notFound, rootRouteId } from '@tanstack/react-router'
export const Route = createFileRoute('/posts/$postId')({
loader: async ({ params: { postId } }) => {
const post = await getPost(postId)
if (!post) throw notFound({ routeId: rootRouteId })
return { post }
},
})
notFoundMode: Fuzzy vs Root
fuzzy (default)
The router finds the nearest parent route with children and a notFoundComponent. Preserves as much parent layout as possible.
Given routes: __root__ → posts → $postId, accessing /posts/1/edit:
- <Root> renders
- <Posts> renders
- <Posts.notFoundComponent> renders (nearest parent with children + notFoundComponent)
root
All not-found errors go to the root route's notFoundComponent, regardless of matching:
const router = createRouter({
routeTree,
notFoundMode: 'root',
})
Error Handling
errorComponent Per Route
errorComponent receives error, info, and reset props. For loader errors, use router.invalidate() to re-run the loader — it automatically resets the error boundary.
// src/routes/posts.$postId.tsx
import { createFileRoute, useRouter } from '@tanstack/react-router'
export const Route = createFileRoute('/posts/$postId')({
loader: async ({ params: { postId } }) => {
const res = await fetch(`/api/posts/${postId}`)
if (!res.ok) throw new Error('Failed to load post')
return res.json()
},
component: PostComponent,
errorComponent: PostErrorComponent,
})
function PostErrorComponent({
error,
}: {
error: Error
info: { componentStack: string }
reset: () => void
}) {
const router = useRouter()
return (
<div>
<p>Error: {error.message}</p>
<button
onClick={() => {
// Invalidate re-runs the loader and resets the error boundary
router.invalidate()
}}
>
Retry
</button>
</div>
)
}
function PostComponent() {
const data = Route.useLoaderData()
return <h1>{data.title}</h1>
}
Router-Wide Default Error Component
const router = createRouter({
routeTree,
defaultErrorComponent: ({ error }) => {
const router = useRouter()
return (
<div>
<p>Something went wrong: {error.message}</p>
<button
onClick={() => {
router.invalidate()
}}
>
Retry
</button>
</div>
)
},
})
Data in notFoundComponent
notFoundComponent cannot reliably use useLoaderData because the loader may not have completed. Safe hooks:
notFoundComponent: ({ data }) => {
// SAFE — always available:
const params = Route.useParams()
const search = Route.useSearch()
const context = Route.useRouteContext()
// UNSAFE — may be undefined:
// const loaderData = Route.useLoaderData()
return <p>Item {params.id} not found</p>
}
To forward partial data, use the data option on notFound():
loader: async ({ params }) => {
const partialData = await getPartialData(params.id)
if (!partialData.fullResource) {
throw notFound({ data: { name: partialData.name } })
}
return partialData
},
notFoundComponent: ({ data }) => {
// data is typed as unknown — validate it
const info = data as { name: string } | undefined
return <p>{info?.name ?? 'Resource'} not found</p>
},
Route Masking
Route masking shows a different URL in the browser bar than the actual route being rendered. Masking data is stored in location.state and is lost when the URL is shared or opened in a new tab.
Imperative Masking on <Link>
import { Link } from '@tanstack/react-router'
function PhotoGrid({ photoId }: { photoId: string }) {
return (
<Link
to="/photos/$photoId/modal"
params={{ photoId }}
mask={{
to: '/photos/$photoId',
params: { photoId },
}}
>
Open Photo
</Link>
)
}
Imperative Masking with useNavigate
import { useNavigate } from '@tanstack/react-router'
function OpenPhotoButton({ photoId }: { photoId: string }) {
const navigate = useNavigate()
return (
<button
onClick={() =>
navigate({
to: '/photos/$photoId/modal',
params: { photoId },
mask: {
to: '/photos/$photoId',
params: { photoId },
},
})
}
>
Open Photo
</button>
)
}
Declarative Masking with createRouteMask
import { createRouter, createRouteMask } from '@tanstack/react-router'
import { routeTree } from './routeTree.gen'
const photoModalMask = createRouteMask({
routeTree,
from: '/photos/$photoId/modal',
to: '/photos/$photoId',
params: (prev) => ({ photoId: prev.photoId }),
})
const router = createRouter({
routeTree,
routeMasks: [photoModalMask],
})
Unmasking on Reload
By default, masks survive local page reloads. To unmask on reload:
// Per-mask
const mask = createRouteMask({
routeTree,
from: '/photos/$photoId/modal',
to: '/photos/$photoId',
params: (prev) => ({ photoId: prev.photoId }),
unmaskOnReload: true,
})
// Per-link
<Link
to="/photos/$photoId/modal"
params={{ photoId }}
mask={{ to: '/photos/$photoId', params: { photoId } }}
unmaskOnReload
>
Open Photo
</Link>
// Router-wide default
const router = createRouter({
routeTree,
unmaskOnReload: true,
})
Common Mistakes
1. HIGH: Using deprecated NotFoundRoute
// WRONG — NotFoundRoute blocks notFound() and notFoundComponent from working
import { NotFoundRoute } from '@tanstack/react-router'
const notFoundRoute = new NotFoundRoute({ component: () => <p>404</p> })
const router = createRouter({ routeTree, notFoundRoute })
// CORRECT — use notFoundComponent on root route
export const Route = createRootRoute({
component: () => <Outlet />,
notFoundComponent: () => <p>404</p>,
})
2. MEDIUM: Expecting useLoaderData in notFoundComponent
// WRONG — loader may not have completed
notFoundComponent: () => {
const data = Route.useLoaderData() // may be undefined!
return <p>{data.title} not found</p>
}
// CORRECT — use safe hooks
notFoundComponent: () => {
const { postId } = Route.useParams()
return <p>Post {postId} not found</p>
}
3. MEDIUM: Leaf routes cannot handle not-found errors
Only routes with children (and therefore an <Outlet>) can render notFoundComponent. Leaf routes (routes without children) will never catch not-found errors — the error bubbles up to the nearest parent with children.
// This route has NO children — notFoundComponent here will not catch
// unmatched child paths (there are no child paths to unmatch)
export const Route = createFileRoute('/posts/$postId')({
// notFoundComponent here only works for notFound() thrown in THIS route's loader
// It does NOT catch path-based not-founds
notFoundComponent: () => <p>Not found</p>,
})
4. MEDIUM: Expecting masked URLs to survive sharing
Masking data lives in location.state (browser history). When a masked URL is copied, shared, or opened in a new tab, the masking data is lost. The browser navigates to the visible (masked) URL directly.
5. HIGH (cross-skill): Using reset() alone instead of router.invalidate()
// WRONG — reset() clears the error boundary but does NOT re-run the loader
function ErrorFallback({ error, reset }: { error: Error; reset: () => void }) {
return <button onClick={reset}>Retry</button>
}
// CORRECT — invalidate re-runs loaders and resets the error boundary
function ErrorFallback({ error }: { error: Error; reset: () => void }) {
const router = useRouter()
return (
<button
onClick={() => {
router.invalidate()
}}
>
Retry
</button>
)
}
Cross-References
- router-core/data-loading — notFound() thrown in loaders interacts with error boundaries and loader data availability. errorComponent retry requires router.invalidate().
- router-core/type-safety — notFoundComponent data is typed as unknown; validate before use.