not-found-and-errors — Claude Code skill: what it does, how to install
not-found-and-errors teaches coding agents to configure 404 boundaries and error components in TanStack Router. It covers throwing notFound() and handling loader failures.
MIT 211 installs ★ 15,341 updated 2026-10-25
npx skills add TanStack/router --skill not-found-and-errors -a claude-codeWhat not-found-and-errors does
TanStack Router separates two types of 404. This skill guides agents through handling unmatched URL paths and manual checks using notFound() inside loader or beforeLoad. The guide details root-level notFoundComponent setup alongside router-wide defaults via defaultNotFoundComponent.
Routing behavior depends on notFoundMode. The default fuzzy setting keeps the closest parent layout active and renders its nearest child boundary. In contrast, root mode directs all not-found events straight to the root component. Route runtime failures rely on errorComponent, where calling router.invalidate() triggers fresh loader runs and resets boundary state.
Do not keep NotFoundRoute. It breaks both notFound() and notFoundComponent across the route tree. Calling useLoaderData inside notFoundComponent is also unsafe because aborted loaders leave data undefined. Safe handlers read useParams or attach partial payloads straight to notFound({ data }).
What it helps with
- Trigger 404 boundaries for missing API items using notFound() inside a loader
- Set up global fallback pages on the root route with notFoundComponent
- Retry failed route loaders by wiring router.invalidate() into errorComponent
- Access route parameters safely inside not-found boundaries without useLoaderData
Example prompts for the agent
- Handle missing records in posts.$postId.tsx by throwing notFound() from the loader
- Build an errorComponent with a retry action that calls router.invalidate()
- Switch router notFoundMode to root and define a defaultNotFoundComponent
How to install not-found-and-errors
1Skills CLI (Vercel)
npx skills add TanStack/router --skill not-found-and-errors -a claude-code2Manually: put the files in place
~/.claude/skills/not-found-and-errors/SKILL.mdCopy the whole skill folder; for one project use .claude/skills/not-found-and-errors/
1Skills CLI (Vercel)
npx skills add TanStack/router --skill not-found-and-errors -a codex2Manually: put the files in place
.agents/skills/not-found-and-errors/SKILL.mdFor all projects use ~/.agents/skills/
1Skills CLI (Vercel)
npx skills add TanStack/router --skill not-found-and-errors -a cursor2Manually: put the files in place
.cursor/skills/not-found-and-errors/SKILL.mdCursor also reads .agents/skills/ and .claude/skills/
1GitHub CLI
gh skill install TanStack/router packages/router-core/skills/router-core/not-found-and-errors2Manually: put the files in place
.github/skills/not-found-and-errors/SKILL.md1Skills CLI (Vercel)
npx skills add TanStack/router --skill not-found-and-errors -a gemini-cli2Platform CLI
gemini skills install https://github.com/TanStack/router --path packages/router-core/skills/router-core/not-found-and-errorsManually: put the files in place
.devin/skills/not-found-and-errors/SKILL.mdThe legacy .windsurf/skills/ path still works
Skills CLI (Vercel)
npx skills add TanStack/router --skill not-found-and-errors -a opencodeClaude.ai
Zip the folder and upload it in Settings → Capabilities → Skills
Step by step, with commands for each platform: How to install skills in Claude Code: five ways
Questions about not-found-and-errors
How do I install not-found-and-errors in Claude Code?
Run npx skills add TanStack/router --skill not-found-and-errors -a claude-code. The skill file is placed in ~/.claude/skills/not-found-and-errors/SKILL.md.
What does not-found-and-errors do?
It provides TanStack Router patterns for unmatched paths, manual 404 exceptions with notFound(), and recovery actions in errorComponent.
Why should NotFoundRoute be removed?
NotFoundRoute is deprecated in TanStack Router and completely disables notFound() and notFoundComponent when left in your route tree.
Source text
SKILL.md · MIT
---
name: not-found-and-errors
description: >-
notFound() function, notFoundComponent, defaultNotFoundComponent,
notFoundMode (fuzzy/root), errorComponent, CatchBoundary,
CatchNotFound, isNotFound, NotFoundRoute (deprecated), route
masking (mask option, createRouteMask, unmaskOnReload).
metadata:
type: sub-skill
library: tanstack-router
library_version: '1.171.15'
requires:
- router-core
sources:
- TanStack/router:docs/router/guide/not-found-errors.md
- TanStack/router:docs/router/guide/route-masking.md
---
# 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
```tsx
// 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`
```tsx
// 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.
```tsx
// 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:
```tsx
// 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`
```tsx
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:
```tsx
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.
```tsx
// 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: unknown
info?: { componentStack: string }
reset: () => void
}) {
const router = useRouter()
return (
<div>
<p>Error: {error instanceof Error ? error.message : String(error)}</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
```tsx
const router = createRouter({
routeTree,
defaultErrorComponent: ({ error }) => {
const router = useRouter()
return (
<div>
<p>
Something went wrong:{' '}
{error instanceof Error ? error.message : String(error)}
</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:
```tsx
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()`:
```tsx
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>`
```tsx
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`
```tsx
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`
```tsx
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:
```tsx
// 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`
```tsx
// 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`
```tsx
// 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.
```tsx
// 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()`
```tsx
// WRONG — reset() clears the error boundary but does NOT re-run the loader
function ErrorFallback({
error,
reset,
}: {
error: unknown
reset: () => void
}) {
return <button onClick={reset}>Retry</button>
}
// CORRECT — invalidate re-runs loaders and resets the error boundary
function ErrorFallback({ error }: { error: unknown; 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.
© TanStack · MIT · TanStack/router