К основному содержанию
скилл CX Codex

not-found-and-errors — скилл для Claude Code

Скилл not-found-and-errors обучает агента настраивать экраны 404 и обработку ошибок в TanStack Router. Помогает пробросить notFound() из loader и оформить запасной UI.

MIT 211 установок ★ 15 341 обновлён 2026-10-25

Установить в Claude Code · Через Skills CLI (Vercel) Все способы и платформы ↓
npx skills add TanStack/router --skill not-found-and-errors -a claude-code
Открыть на GitHub

Что делает not-found-and-errors

У роутера два типа 404. Скилл объясняет автоматический перехват неизвестных путей и ручной вызов notFound() внутри loader или beforeLoad. Агент учится задавать notFoundComponent на корневом маршруте и defaultNotFoundComponent для всего роутера.

Внутри описаны режимы notFoundMode. По умолчанию включён fuzzy: роутер ищет ближайшего предка с компонентом ошибки, сохраняя окружающий макет. При режиме root все ошибки 404 уходят на самый верх. Для перехвата сбоев скилл предлагает errorComponent, где кнопка повтора вызывает router.invalidate().

Устаревший NotFoundRoute использовать нельзя. Его присутствие полностью ломает работу notFound() и notFoundComponent. Внутри notFoundComponent также нельзя вызывать useLoaderData: данные загрузчика могут не существовать, поэтому безопаснее брать useParams или прокидывать контекст через аргументы notFound().

Какие задачи решает

  • Настроить глобальный экран 404 на корневом маршруте через notFoundComponent
  • Выбросить ошибку отсутствующей записи через notFound() внутри loader
  • Организовать повторную загрузку данных по кнопке через router.invalidate()
  • Безопасно прочитать параметры в компоненте ошибки без вызова useLoaderData

Примеры запросов агенту

  • Добавь обработку 404 через notFound() в loader маршрута posts.$postId.tsx
  • Настрой errorComponent с кнопкой повтора запроса через router.invalidate()
  • Переведи notFoundMode роутера в режим root и добавь defaultNotFoundComponent

Как установить not-found-and-errors

1Через Skills CLI (Vercel)

npx skills add TanStack/router --skill not-found-and-errors -a claude-code

2Вручную: положить файлы

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

Папка скилла целиком; для одного проекта — .claude/skills/not-found-and-errors/

По шагам, с командами для каждой платформы: Как установить скилл в Claude Code: пять способов

Вопросы о not-found-and-errors

Как установить not-found-and-errors в Claude Code?

Выполните команду npx skills add TanStack/router --skill not-found-and-errors -a claude-code. Файл навыка появится по пути ~/.claude/skills/not-found-and-errors/SKILL.md.

Зачем нужен скилл not-found-and-errors?

Он задаёт модели правила TanStack Router для обработки отсутствующих страниц, вызова notFound() в загрузчиках и оформления границ errorComponent.

Почему нельзя использовать useLoaderData внутри notFoundComponent?

При ошибке 404 выполнение loader прерывается, поэтому useLoaderData может вернуть undefined. Безопаснее читать параметры через useParams, useSearch или передавать данные в вызове notFound({ data }).

Исходный текст

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

Похожие скиллы

Все скиллы по теме «Фронтенд и UI» →
tanstack-router-best-practices DeckardGer Скилл tanstack-router-best-practices для Claude Code: правила по TanStack Router для React — типизация, загрузка данных, search params и навигация. Структурирует роутинг в растущих проектах. CX Codex +1 7 200установок tanstack-router oakoss Скилл tanstack-router настраивает типобезопасную файловую маршрутизацию в React через @tanstack/react-router. Помогает с лоадерами данных, валидацией параметров поиска и разделением кода. CX Codex +1 150установок status-colors-and-errors dembrandt Скилл status-colors-and-errors задаёт правила для семантических цветов статусов и текстов ошибок: сколько цветов держать, что каждый значит и как написать сообщение с выходом из ситуации. CX Codex +1 1 000установок recovering-from-errors oxbshw Скилл recovering-from-errors разбирает сбои Watch Skill: читает код ошибки, запускает watch-skill doctor и повторяет упавшую команду один раз. CX Codex +1 734установок dart-fix-runtime-errors dart-lang Скилл dart-fix-runtime-errors автоматически ловит ошибки времени выполнения в Dart-коде, находит проблемную строку через LSP и стек-трейс, применяет исправление и проверяет результат через hot reload. CX Codex +1 20 800установок w-errors blockmatic-icebox Скилл w-errors для Claude Code добавляет обработку ошибок по правилам проекта. Запускается по явному запросу при работе с изменённым кодом. CX Codex +1 647установок

Из того же набора25

Весь набор →
auth-and-guards Скилл auth-and-guards для защиты маршрутов в TanStack Router. Перенаправляет неавторизованных пользователей, встраивает проверку ролей и прав, интегрирует Auth0, Clerk, Supabase через контекст роутера. CX Codex +1 219установок navigation Скилл navigation помогает агенту настраивать навигацию в TanStack Router: ссылки, переходы, предзагрузку маршрутов и блокировку ухода со страницы. CX Codex +1 214установок execution-model Скилл execution-model помогает агенту правильно разделять серверный и клиентский код в TanStack Start и учитывать SSR, гидрацию и переменные окружения. CX Codex +1 214установок code-splitting Скилл code-splitting разделяет код маршрутов TanStack Router на критичную и ленивую части: автоматически создаёт отдельные чанки или позволяет настроить разделение вручную. CX Codex +1 212установок deployment Скилл deployment разворачивает приложения TanStack Start на Cloudflare Workers, Netlify, Vercel, Node.js, Bun и Railway. Управляет SSR по маршрутам, статическим пререндерингом и SEO. CX Codex +1 210установок path-params Скилл path-params для работы с динамическими параметрами в URL-адресах маршрутов TanStack Router. Позволяет захватывать переменные части пути, настраивать опциональные сегменты и создавать шаблоны с префиксами и суффиксами. CX Codex +1 208установок middleware Учит работать с middleware-цепочками TanStack Start. Покрывает createMiddleware, передачу контекста через next(), sendContext и глобальные хуки через src/start.ts. CX Codex +1 206установок server-routes Скилл server-routes для Claude Code создаёт серверные API-маршруты в TanStack Router и разбирает HTTP-запросы. Эндпоинты размещаются рядом с маршрутами приложения. CX Codex +1 205установок

Спонсоры проекта

Компании, которые помогают держать аналитику открытой