diff --git a/docs/02-app/01-building-your-application/01-routing/07-error-handling.mdx b/docs/02-app/01-building-your-application/01-routing/07-error-handling.mdx index 3f47ae2c6e570..ef5098639969d 100644 --- a/docs/02-app/01-building-your-application/01-routing/07-error-handling.mdx +++ b/docs/02-app/01-building-your-application/01-routing/07-error-handling.mdx @@ -1,13 +1,16 @@ --- title: Error Handling description: Handle runtime errors by automatically wrapping route segments and their nested children in a React Error Boundary. +related: + links: + - app/api-reference/file-conventions/error --- -The `error.js` file convention allows you to gracefully handle runtime errors in [nested routes](/docs/app/building-your-application/routing#nested-routes). +The `error.js` file convention allows you to gracefully handle unexpected runtime errors in [nested routes](/docs/app/building-your-application/routing#nested-routes). - Automatically wrap a route segment and its nested children in a [React Error Boundary](https://react.dev/reference/react/Component#catching-rendering-errors-with-an-error-boundary). - Create error UI tailored to specific segments using the file-system hierarchy to adjust granularity. -- Isolate errors to affected segments while keeping the rest of the app functional. +- Isolate errors to affected segments while keeping the rest of the application functional. - Add functionality to attempt to recover from an error without a full page reload. Create error UI by adding an `error.js` file inside a route segment and exporting a React component: @@ -154,7 +157,7 @@ The nested component hierarchy has implications for the behavior of `error.js` f ### Handling Errors in Layouts -`error.js` boundaries do **not** catch errors thrown in `layout.js` or `template.js` components of the same segment. This [intentional hierarchy](#nested-routes) keeps important UI that is shared between sibling routes (such as navigation) visible and functional when an error occurs. +`error.js` boundaries do **not** catch errors thrown in `layout.js` or `template.js` components of the **same segment**. This [intentional hierarchy](#nested-routes) keeps important UI that is shared between sibling routes (such as navigation) visible and functional when an error occurs. To handle errors within a specific layout or template, place an `error.js` file in the layouts parent segment. @@ -210,6 +213,14 @@ export default function GlobalError({ error, reset }) { ### Handling Server Errors -If an error is thrown during [data fetching](/docs/app/building-your-application/data-fetching/fetching) or inside a Server Component, Next.js will forward the resulting `Error` object to the nearest `error.js` file as the `error` prop. +If an error is thrown inside a Server Component, Next.js will forward an `Error` object (stripped of sensitive error information in production) to the nearest `error.js` file as the `error` prop. -When running `next dev`, the `error` will be serialized and forwarded from the Server Component to the client `error.js`. To ensure security when running `next start` in production, a generic error message is forwarded to `error` along with a `.digest` which contains a hash of the error message. This hash can be used to correspond to server logs. +#### Securing Sensitive Error Information + +During production, the `Error` object forwarded to the client only includes a generic `message` and `digest` property. + +This is a security precaution to avoid leaking potentially sensitive details included in the error to the client. + +The `message` property contains a generic message about the error and the `digest` property contains an automatically generated hash of the error that can be used to match the corresponding error in server-side logs. + +During development, the `Error` object forwarded to the client will be serialized and include the `message` of the original error for easier debugging. diff --git a/docs/02-app/02-api-reference/02-file-conventions/error.mdx b/docs/02-app/02-api-reference/02-file-conventions/error.mdx index 249ce417a4843..3b920e245a9a9 100644 --- a/docs/02-app/02-api-reference/02-file-conventions/error.mdx +++ b/docs/02-app/02-api-reference/02-file-conventions/error.mdx @@ -1,10 +1,16 @@ --- title: error.js description: API reference for the error.js special file. +related: + title: Learn more about error handling + links: + - app/building-your-application/routing/error-handling --- An **error** file defines an error UI boundary for a route segment. +It is useful for catching **unexpected** errors that occur in Server Components and Client Components and displaying a fallback UI. + ```tsx filename="app/dashboard/error.tsx" switcher 'use client' // Error components must be Client Components @@ -14,7 +20,7 @@ export default function Error({ error, reset, }: { - error: Error + error: Error & { digest?: string } reset: () => void }) { useEffect(() => { @@ -69,15 +75,29 @@ export default function Error({ error, reset }) { ### `error` -An instance of an [`Error`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Error) object. This error can happen on the server or the client. +An instance of an [`Error`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Error) object forwarded to the `error.js` Client Component. + +#### `error.message` + +The error message. + +- For errors forwarded from Client Components, this will be the original Error's message. +- For errors forwarded from Server Components, this will be a generic error message to avoid leaking sensitive details. `errors.digest` can be used to match the corresponding error in server-side logs. + +#### `error.digest` + +An automatically generated hash of the error thrown in a Server Component. It can be used to match the corresponding error in server-side logs. ### `reset` -A function to reset the error boundary, which does not return a response. +A function to reset the error boundary. 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. + +Can be used to prompt the user to attempt to recover from the error. > **Good to know**: > > - `error.js` boundaries must be **[Client Components](/docs/getting-started/react-essentials)**. +> - In Production builds, errors forwarded from Server Components will be stripped of specific error details to avoid leaking sensitive information. > - An `error.js` boundary will **not** handle errors thrown in a `layout.js` component in the **same** segment because the error boundary is nested **inside** that layouts component. > - To handle errors for a specific layout, place an `error.js` file in the layouts parent segment. > - To handle errors within the root layout or template, use a variation of `error.js` called `app/global-error.js`. @@ -93,7 +113,7 @@ export default function GlobalError({ error, reset, }: { - error: Error + error: Error & { digest?: string } reset: () => void }) { return (