Fix Error: Error: Custom 404 page could not be rendered. pages/404.tsx has an error. in Next.js

This error occurs when your custom 404 page has a runtime or build-time error, causing Next.js to fail when rendering the not-found page. Common causes include importing server-only modules, using hooks incorrectly, or having syntax errors. Fix it by ensuring the 404 page is a simple static component with no data-fetching methods.

Reading the Stack Trace

Here's what each line means:

• at renderToHTML (/app/node_modules/next/dist/server/render.js:902:15): The server-side rendering of the 404 page failed, preventing Next.js from showing the custom not-found page.
• at async DevServer.render404 (/app/node_modules/next/dist/server/base-server.js:1472:25): Next.js attempted to render the custom 404 page but encountered an error in the component itself.
• at async DevServer.renderErrorToHTML (/app/node_modules/next/dist/server/base-server.js:1589:32): The error rendering pipeline tried to show the 404 page but it also errored, creating a cascading failure.

Common Causes

export async function getServerSideProps() {
  const suggestions = await fetch('/api/suggestions');
  return { props: { suggestions: await suggestions.json() } };
}

export default function NotFound({ suggestions }) {
  return <div>Page not found. Try: {suggestions.join(', ')}</div>;
}

import confetti from 'canvas-confetti';

export default function NotFound() {
  confetti(); // Crashes during SSG - no canvas available
  return <div>404 - Page not found</div>;
}

export default function NotFound() {
  const links = undefined;
  return (
    <div>
      <h1>404</h1>
      {links.map(l => <a key={l.href} href={l.href}>{l.text}</a>)}
    </div>
  );
}

The Fix

Remove getServerSideProps and any server-only dependencies from the 404 page. Custom 404 pages in Next.js are statically generated, so they must be simple components with no data-fetching methods. Use getStaticProps if you need data at build time.

export async function getServerSideProps() {
  const suggestions = await fetch('/api/suggestions');
  return { props: { suggestions: await suggestions.json() } };
}

export default function NotFound({ suggestions }) {
  return <div>Page not found. Try: {suggestions.join(', ')}</div>;
}

import Link from 'next/link';

export default function NotFound() {
  return (
    <div className="flex flex-col items-center justify-center min-h-screen">
      <h1 className="text-4xl font-bold">404</h1>
      <p className="mt-4 text-lg">Page not found</p>
      <Link href="/" className="mt-6 text-blue-600 hover:underline">
        Go back home
      </Link>
    </div>
  );
}

Testing the Fix

import { render, screen } from '@testing-library/react';
import NotFound from '@/pages/404';

describe('404 Page', () => {
  it('renders the 404 heading', () => {
    render(<NotFound />);
    expect(screen.getByText('404')).toBeInTheDocument();
  });

  it('renders a link back to home', () => {
    render(<NotFound />);
    const link = screen.getByRole('link', { name: /go back home/i });
    expect(link).toHaveAttribute('href', '/');
  });

  it('renders the page not found message', () => {
    render(<NotFound />);
    expect(screen.getByText('Page not found')).toBeInTheDocument();
  });
});

Run your tests:

npm test

Pushing Through CI/CD

git checkout -b fix/custom-404-page-error,git add src/pages/404.tsx src/pages/__tests__/404.test.tsx,git commit -m "fix: simplify custom 404 page to avoid SSG errors",git push origin fix/custom-404-page-error

Your CI config should look something like this:

name: CI
on:
  pull_request:
    branches: [main]
jobs:
  test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: '20'
          cache: 'npm'
      - run: npm ci
      - run: npm test -- --coverage
      - run: npm run build

The Full Manual Process: 18 Steps

Here's every step you just went through to fix this one bug:

1. Notice the error alert or see it in your monitoring tool
2. Open the error dashboard and read the stack trace
3. Identify the file and line number from the stack trace
4. Open your IDE and navigate to the file
5. Read the surrounding code to understand context
6. Reproduce the error locally
7. Identify the root cause
8. Write the fix
9. Run the test suite locally
10. Fix any failing tests
11. Write new tests covering the edge case
12. Run the full test suite again
13. Create a new git branch
14. Commit and push your changes
15. Open a pull request
16. Wait for code review
17. Merge and deploy to production
18. Monitor production to confirm the error is resolved

Total time: 30-60 minutes. For one bug.

npm install bugstack-sdk

import { initBugStack } from 'bugstack-sdk'

initBugStack({ apiKey: process.env.BUGSTACK_API_KEY })

Deploying the Fix (Manual Path)

1. Run the test suite locally to verify the 404 page renders correctly.
2. Open a pull request with the simplified 404 page.
3. Wait for CI checks to pass on the PR.
4. Have a teammate review and approve the PR.
5. Merge to main and verify the 404 page works in staging.

Frequently Asked Questions