How to Create a Custom Error Page in Next.js

In Next.js, create a custom error page by adding a pages/_error.js file that exports a React component to handle errors globally. This component can customize the UI for HTTP errors like 404 or 500, improving user experience.

Syntax

To create a custom error page in Next.js, add a file named _error.js inside the pages folder. Export a React component that receives statusCode as a prop to display different messages based on the error type.

The component can also implement getInitialProps to fetch the error status code from the server or client.

javascript

import React from 'react';

function Error({ statusCode }) {
  return (
    <p>
      {statusCode
        ? `An error ${statusCode} occurred on server`
        : 'An error occurred on client'}
    </p>
  );
}

Error.getInitialProps = ({ res, err }) => {
  const statusCode = res ? res.statusCode : err ? err.statusCode : 404;
  return { statusCode };
};

export default Error;

Output

Displays a message like 'An error 404 occurred on server' or 'An error occurred on client' depending on error context.

Example

This example shows a complete custom error page that displays a friendly message for 404 and 500 errors, and a generic message for others. It uses Next.js's _error.js file to catch errors globally.

javascript

import React from 'react';
import Link from 'next/link';

function Error({ statusCode }) {
  return (
    <main style={{ textAlign: 'center', padding: '2rem' }}>
      <h1>
        {statusCode === 404
          ? 'Page Not Found'
          : statusCode === 500
          ? 'Internal Server Error'
          : 'An Unexpected Error Occurred'}
      </h1>
      <p>
        {statusCode === 404
          ? 'Sorry, the page you are looking for does not exist.'
          : 'Please try again later.'}
      </p>
      <Link href="/">
        <a style={{ color: '#0070f3', textDecoration: 'underline' }}>Go back home</a>
      </Link>
    </main>
  );
}

Error.getInitialProps = ({ res, err }) => {
  const statusCode = res ? res.statusCode : err ? err.statusCode : 404;
  return { statusCode };
};

export default Error;

Output

Renders a centered message: 'Page Not Found' for 404, 'Internal Server Error' for 500, or a generic error message, with a link to go back home.

Common Pitfalls

• Not naming the file _error.js exactly will prevent Next.js from using it as the error page.
• Forgetting to export the component as default causes the page not to load.
• Not handling getInitialProps properly can lead to missing status codes and incorrect messages.
• Using client-only code inside getInitialProps can cause errors since it runs on server and client.

javascript

/* Wrong: Missing default export and wrong file name */
// File named error.js instead of _error.js
function ErrorPage() {
  return <p>Error occurred</p>;
}

/* Right: Correct file name and default export */
// File named _error.js
export default function Error({ statusCode }) {
  return <p>Error {statusCode}</p>;
}

Quick Reference

Remember these key points when creating a custom error page in Next.js:

• Use pages/_error.js for global error handling.
• Export a default React component that accepts statusCode as a prop.
• Implement getInitialProps to get the error status code.
• Customize UI based on statusCode for better user experience.

Key Takeaways

Create a file named _error.js inside the pages folder to customize error pages in Next.js.

Export a default React component that uses the statusCode prop to show different messages.

Implement getInitialProps to retrieve the error status code from server or client context.

Handle common HTTP errors like 404 and 500 with friendly messages to improve UX.

Ensure the file is named exactly _error.js and the component is the default export.