Skip to main content
The error.js file defines a fallback UI for unexpected runtime errors within a route segment. It wraps the segment and its nested children in a React Error Boundary.
app/dashboard/error.js
'use client' // Error boundaries must be Client Components

import { useEffect } from 'react'

export default function Error({ error, unstable_retry }) {
  useEffect(() => {
    console.error(error)
  }, [error])

  return (
    <div>
      <h2>Something went wrong!</h2>
      <button onClick={() => unstable_retry()}>Try again</button>
    </div>
  )
}
Error boundaries must be Client Components. Add 'use client' at the top of the file.

​
Props

​
error
Error & { digest?: string }
An Error object forwarded to the Client Component.
  • In development — includes the original error message for easier debugging
  • In production — shows a generic message to avoid leaking sensitive information. Use error.digest to correlate with server-side logs.
​
error.message
string
The human-readable error message. For errors from Client Components, this is the original message. For Server Component errors, this is a generic message with an identifier to match server-side logs.
​
error.digest
string
An automatically generated hash of the thrown error. Use it to match the error in your server-side logs.
​
unstable_retry
function
Re-fetches and re-renders the error boundary’s children. If successful, the error fallback is replaced with the re-rendered content.Use this for transient errors where retrying is likely to succeed.
​
reset
function
Clears the error state and re-renders the error boundary’s children without re-fetching. Use this when you want to clear the error state without a network request.In most cases, prefer unstable_retry() over reset().

​
Behavior

  • error.js wraps loading.js, not-found.js, page.js, and nested layout.js files in an error boundary
  • It does not wrap the layout.js or template.js in the same segment
  • To handle errors in the root layout, use global-error.js
  • Throwing inside an error component bubbles the error up to the parent error boundary

​
Examples

​
Basic error boundary

app/dashboard/error.js
'use client'

export default function Error({ error, unstable_retry }) {
  return (
    <div>
      <h2>Something went wrong!</h2>
      <p>{error.message}</p>
      <button onClick={() => unstable_retry()}>Try again</button>
    </div>
  )
}

​
Logging errors to a reporting service

app/dashboard/error.js
'use client'

import { useEffect } from 'react'

export default function Error({ error, unstable_retry }) {
  useEffect(() => {
    // Log to your error reporting service
    reportError({ message: error.message, digest: error.digest })
  }, [error])

  return (
    <div>
      <h2>Something went wrong!</h2>
      <p>Error ID: {error.digest}</p>
      <button onClick={() => unstable_retry()}>Try again</button>
    </div>
  )
}

​
Global error

To handle errors in the root layout or template, use app/global-error.js. This file replaces the entire root layout when active, so it must include its own <html> and <body> tags.
app/global-error.js
'use client'

export default function GlobalError({ error, unstable_retry }) {
  return (
    <html>
      <body>
        <h2>Something went wrong!</h2>
        <button onClick={() => unstable_retry()}>Try again</button>
      </body>
    </html>
  )
}
global-error.js must be a Client Component. The metadata export and generateMetadata are not supported. Use React’s <title> component as an alternative.

​
Version history

VersionChanges
v16.2.0unstable_retry prop added
v15.2.0global-error also displayed in development
v13.1.0global-error introduced
v13.0.0error introduced

Build docs developers (and LLMs) love

Get started for freeTalk to us