> ## Documentation Index
> Fetch the complete documentation index at: https://mintlify.com/tanstack/router/llms.txt
> Use this file to discover all available pages before exploring further.
# Error handling
> Handle errors gracefully with error boundaries and error components
TanStack Router provides robust error handling through error boundaries that catch and display errors from loaders, components, and navigation.
## Error components
Define custom error boundaries at route level:
```tsx theme={null}
import { createFileRoute, ErrorComponent } from '@tanstack/react-router'
export const Route = createFileRoute('/posts/$postId')({
loader: async ({ params }) => {
const post = await fetchPost(params.postId)
if (!post) throw new Error('Post not found')
return { post }
},
errorComponent: PostErrorComponent,
})
function PostErrorComponent({ error, reset }: ErrorComponentProps) {
return (
Error Loading Post
{error.message}
)
}
```
## Error component props
Error components receive helpful props:
```tsx theme={null}
import type { ErrorComponentProps } from '@tanstack/react-router'
function MyErrorComponent({ error, info, reset }: ErrorComponentProps) {
// error - The thrown error
console.error(error)
// info - React error boundary info
console.log(info?.componentStack)
// reset - Function to retry/reset the error boundary
const handleRetry = () => {
reset()
}
return (
Something went wrong
{error.message}
)
}
```
## Root error boundary
Catch errors from all routes:
```tsx theme={null}
import { createRootRoute, ErrorComponent } from '@tanstack/react-router'
export const Route = createRootRoute({
errorComponent: RootErrorComponent,
component: RootComponent,
})
function RootErrorComponent({ error, reset }: ErrorComponentProps) {
return (
Application Error
{error.message}
)
}
```
## Throwing errors in loaders
Throw errors during data loading:
```tsx theme={null}
export const Route = createFileRoute('/posts/$postId')({
loader: async ({ params }) => {
const post = await fetchPost(params.postId)
if (!post) {
throw new Error('Post not found')
}
if (!post.published) {
throw new Error('This post is not published yet')
}
return { post }
},
})
```
## Custom error types
Create typed errors for better handling:
```tsx theme={null}
class NotFoundError extends Error {
constructor(resource: string) {
super(`${resource} not found`)
this.name = 'NotFoundError'
}
}
class UnauthorizedError extends Error {
constructor() {
super('You are not authorized to view this resource')
this.name = 'UnauthorizedError'
}
}
export const Route = createFileRoute('/posts/$postId')({
loader: async ({ params, context }) => {
if (!context.auth.isAuthenticated) {
throw new UnauthorizedError()
}
const post = await fetchPost(params.postId)
if (!post) {
throw new NotFoundError('Post')
}
return { post }
},
errorComponent: ({ error, reset }) => {
if (error instanceof UnauthorizedError) {
return
}
if (error instanceof NotFoundError) {
return (
404 - {error.message}
Go Home
)
}
return (
Unexpected Error
{error.message}
)
},
})
```
## Component errors
Error boundaries also catch component errors:
```tsx theme={null}
function PostComponent() {
const { post } = Route.useLoaderData()
// This error will be caught by errorComponent
if (!post.content) {
throw new Error('Post has no content')
}
return {post.content}
}
```
## Resetting errors
The `reset` function retries the failed operation:
```tsx theme={null}
function ErrorComponent({ error, reset }: ErrorComponentProps) {
const [retryCount, setRetryCount] = React.useState(0)
const handleRetry = () => {
setRetryCount((c) => c + 1)
reset()
}
return (
Error: {error.message}
Retry attempts: {retryCount}
)
}
```
## Default error component
Use the built-in error component:
```tsx theme={null}
import { ErrorComponent } from '@tanstack/react-router'
export const Route = createFileRoute('/posts/$postId')({
errorComponent: ErrorComponent,
})
```
## Not found errors
Handle 404 errors separately:
```tsx theme={null}
import { notFound } from '@tanstack/react-router'
export const Route = createFileRoute('/posts/$postId')({
loader: async ({ params }) => {
const post = await fetchPost(params.postId)
if (!post) throw notFound()
return { post }
},
notFoundComponent: () => (
Post Not Found
View All Posts
),
})
```
## Error logging
Log errors to external services:
```tsx theme={null}
import * as Sentry from '@sentry/react'
function GlobalErrorComponent({ error, info }: ErrorComponentProps) {
React.useEffect(() => {
Sentry.captureException(error, {
extra: {
componentStack: info?.componentStack,
},
})
}, [error, info])
return
An error occurred. Our team has been notified.
}
```
## Best practices
Give users context about what went wrong and how to recover.
Allow users to retry failed operations.
Create custom error classes for better error handling and recovery.
Integrate with error tracking services like Sentry or LogRocket.
## Next steps
Learn about loader error handling
Explore error configuration options