Skip to main content
skill CX Codex

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

Install into Claude Code · Skills CLI (Vercel) All methods and platforms ↓
npx skills add TanStack/router --skill not-found-and-errors -a claude-code
Open on GitHub

What 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-code

2Manually: put the files in place

~/.claude/skills/not-found-and-errors/SKILL.md

Copy the whole skill folder; for one project use .claude/skills/not-found-and-errors/

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

Similar skills

All skills for Frontend and UI →

From the same set25

The whole set →
auth-and-guards auth-and-guards — a skill for protecting routes in TanStack Router. Redirects unauthenticated users, embeds role and permission checks, integrates Auth0, Clerk, Supabase via router context. CX Codex +1 219installs navigation This skill guides TanStack Router navigation with links, programmatic transitions, route preloading, and protection against leaving dirty forms. CX Codex +1 214installs execution-model The execution-model skill teaches agents to separate server and browser code in TanStack Start, with SSR, hydration, imports, and environment variables in view. CX Codex +1 214installs code-splitting code-splitting — a skill for TanStack Router that splits route code into critical (config, loaders) and lazy (components). Automatically generates separate chunks per route, or manually control splitting with .lazy.tsx files. CX Codex +1 212installs deployment deployment deploys TanStack Start to Cloudflare Workers, Netlify, Vercel, Node.js, Bun, and Railway. Controls SSR per route, static prerendering, and SEO config. CX Codex +1 210installs path-params path-params — a skill for handling dynamic URL parameters in TanStack Router. Teaches agents to capture variable path segments, set up optional routes, and create patterns with prefixes and suffixes. CX Codex +1 208installs middleware Covers TanStack Start middleware: createMiddleware, context chaining via next(), sendContext for cross-boundary transfers, and global registration in src/start.ts. CX Codex +1 206installs server-routes This skill guides an agent through API endpoints in TanStack Router, including HTTP handlers and request parsing. Use it when routes need an HTTP contract. CX Codex +1 205installs

Project sponsors

Companies that keep this analytics open