You are currently viewing documentation for the canary channel of Next.js.

error.js

An error file allows you to handle unexpected runtime errors and display fallback UI.

app/dashboard/error.tsx

'use client' // Error boundaries must be Client Components
 
import { useEffect } from 'react'
 
export default function Error({
  error,
  reset,
}: {
  error: Error & { digest?: string }
  reset: () => void
}) {
  useEffect(() => {
    // Log the error to an error reporting service
    console.error(error)
  }, [error])
 
  return (
    <div>
      <h2>Something went wrong!</h2>
      <button
        onClick={
          // Attempt to recover by trying to re-render the segment
          () => reset()
        }
      >
        Try again
      </button>
    </div>
  )
}

How `error.js` Works

error.js wraps a route segment and its nested children in a React Error Boundary. When an error throws within the boundary, the error component shows as the fallback UI.

Good to know:

The React DevTools allow you to toggle error boundaries to test error states.

Props

`error`

An instance of an Error object forwarded to the error.js Client Component.

Good to know: During development, the Error object forwarded to the client will be serialized and include the message of the original error for easier debugging. However, this behavior is different in production to avoid leaking potentially sensitive details included in the error to the client.

`error.message`

Errors forwarded from Client Components show the original Error message.
Errors forwarded from Server Components show a generic message with an identifier. This is to prevent leaking sensitive details. You can use the identifier, under errors.digest, to match the corresponding server-side logs.

`error.digest`

An automatically generated hash of the error thrown. It can be used to match the corresponding error in server-side logs.

`reset`

The cause of an error can sometimes be temporary. In these cases, trying again might resolve the issue.

An error component can use the reset() function to prompt the user to attempt to recover from the error. When executed, the function will try to re-render the error boundary's contents. If successful, the fallback error component is replaced with the result of the re-render.

app/dashboard/error.tsx

'use client' // Error boundaries must be Client Components
 
export default function Error({
  error,
  reset,
}: {
  error: Error & { digest?: string }
  reset: () => void
}) {
  return (
    <div>
      <h2>Something went wrong!</h2>
      <button onClick={() => reset()}>Try again</button>
    </div>
  )
}

`global-error.js`

While less common, you can handle errors in the root layout or template using app/global-error.js, located in the root app directory, even when leveraging internationalization. Global error UI must define its own <html> and <body> tags. This file replaces the root layout or template when active.

app/global-error.tsx

'use client' // Error boundaries must be Client Components
 
export default function GlobalError({
  error,
  reset,
}: {
  error: Error & { digest?: string }
  reset: () => void
}) {
  return (
    // global-error must include html and body tags
    <html>
      <body>
        <h2>Something went wrong!</h2>
        <button onClick={() => reset()}>Try again</button>
      </body>
    </html>
  )
}

Good to know:

global-error.js is only enabled in production. In development, our error overlay will show instead.

not-found.js

The not-found file shows UI when calling the notFound() function within a route segment.

Version History

Version	Changes
`v13.1.0`	`global-error` introduced.
`v13.0.0`	`error` introduced.