Next.js Error Pages: not-found, error.js, Global Error and Middleware

How Next.js error handling works

Next.js gives you a separate file for each kind of failure, and each one has a different job. If you mix them up, visitors see a blank screen, or Google sees a page that says it is missing but answers with a 200 status code. Getting the files right is mostly about knowing which failure each one catches.

In the App Router (the app folder), these are the files that matter:

The Pages Router (the pages folder) uses older equivalents: pages/404.js for missing pages, pages/500.js for server errors, and pages/_error.js as a catch-all that receives the status code. Both routers can live in the same project, and the App Router files take over for routes inside app.

Two rules explain most problems. First, error.js is a React error boundary, so it wraps the segment's page and children, but not the layout.js in the same folder. An error in a layout bubbles up to the parent segment's error.js, and an error in the root layout goes to global-error.js. Second, the status code is decided by the server when the response starts. Once Next.js has begun streaming HTML to the browser, it cannot change the status, so a notFound() call that happens late in a streamed page is sent with a 200 and a noindex robots tag instead of a 404.

Common causes of broken error pages in Next.js

Most Next.js error page problems come from a short list of mistakes. Check your project against this table before you change any code.

The first row is the one that hurts search the most. A catch-all or dynamic route that shows a friendly message for an unknown slug, without calling notFound(), turns every mistyped or deleted URL into an indexable thin page. Our 404 errors guide explains why a real 404 is the right answer for content that has gone.

How to diagnose the problem

Start by finding out what status code each failing URL really returns. The browser page can look correct while the status is wrong, so test with curl rather than by eye:

# Status line and headers only
curl -sI https://www.example.com/products/does-not-exist

# Follow redirects and print just the final status
curl -s -o /dev/null -w "%{http_code} %{url_effective}\n" -L https://www.example.com/old-page

# Look for the noindex tag Next.js adds when the status could not be changed
curl -s https://www.example.com/products/does-not-exist | grep -i 'name="robots"'

A missing page should print 404. If it prints 200 and the grep finds a noindex robots tag, the page is streaming before notFound() runs. If it prints 200 with no robots tag, the route is not calling notFound() at all.

Finding a MIDDLEWARE_INVOCATION_FAILED error

On Vercel, this 500 means the middleware function threw or could not run. The error page shows only the code and an ID, so you need the logs. Open the project in the Vercel dashboard, go to Logs, and filter by the failing path. The log entry for the middleware invocation holds the real exception, such as a TypeError or a missing module. From the command line you can stream logs for a deployment:

npx vercel logs https://my-app-abc123.vercel.app

Reproduce locally with next build followed by next start, not just next dev. The development server is more forgiving, and some middleware errors only appear in a production build.

Checking for client-side errors

If the page renders and then turns white, open Chrome DevTools, go to the Console, and reload. The first red error is usually the cause. A missing error.js above that component is why the whole page disappears instead of showing a recovery message. For broader checks across a site, the Next.js site audit guide covers crawling a build for status codes.

The key files and code

A not-found page that returns a real 404

Put not-found.js at the root of app so it handles every unmatched URL. Keep it a Server Component and avoid slow data calls in it.

// app/not-found.js
import Link from 'next/link';

export const metadata = { title: 'Page not found | Example Bakery' };

export default function NotFound() {
  return (
    <main>
      <h1>We could not find that page</h1>
      <p>The page may have moved or been removed.</p>
      <Link href="/">Back to the home page</Link>
    </main>
  );
}

Then make every dynamic route call notFound() as soon as it knows the item does not exist, before anything streams:

// app/products/[slug]/page.js
import { notFound } from 'next/navigation';
import { getProduct } from '@/lib/products';

export default async function ProductPage({ params }) {
  const { slug } = await params;
  const product = await getProduct(slug);
  if (!product) notFound();
  return <h1>{product.name}</h1>;
}

Call the same check in generateMetadata if the route has one. Metadata is resolved before the page streams, so a notFound() there reliably produces a 404. Avoid wrapping the whole page in a loading.js or a Suspense boundary that starts streaming before the lookup finishes.

An error boundary for a segment

// app/products/error.js
'use client';

import { useEffect } from 'react';

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

  return (
    <div>
      <h2>Something went wrong loading this page</h2>
      <button onClick={() => reset()}>Try again</button>
    </div>
  );
}

The 'use client' line is required, because error boundaries run in the browser. In production, server errors reach the component with a generic message and a digest value so that secrets are not leaked; search your server logs for that digest to find the real stack trace.

A global error page

// app/global-error.js
'use client';

export default function GlobalError({ error, reset }) {
  return (
    <html lang="en">
      <body>
        <h1>Sorry, the site had a problem</h1>
        <button onClick={() => reset()}>Try again</button>
      </body>
    </html>
  );
}

Because it replaces the root layout when it is active, global-error.js must render its own <html> and <body> tags. It does not get your layout's fonts or stylesheets, so keep it simple.

Middleware that cannot crash the request

// middleware.js (in Next.js 16: proxy.js, exporting a function named proxy)
import { NextResponse } from 'next/server';

export function middleware(request) {
  try {
    const country = request.headers.get('x-vercel-ip-country') || 'GB';
    const res = NextResponse.next();
    res.headers.set('x-country', country);
    return res;
  } catch (err) {
    console.error('middleware failed', err);
    return NextResponse.next();
  }
}

export const config = {
  matcher: ['/((?!_next/static|_next/image|favicon.ico|robots.txt|sitemap.xml).*)'],
};

The matcher stops middleware running on static files, which cuts the number of invocations and the chance of a failure on assets. The try and catch turns an unexpected error into a logged warning and a normal response rather than a 500 for every visitor.

Fixing MIDDLEWARE_INVOCATION_FAILED on Vercel

The full message usually reads 500: INTERNAL_SERVER_ERROR with Code: MIDDLEWARE_INVOCATION_FAILED and an ID. It means Vercel started your middleware and it ended with an unhandled error. Every request the matcher covers fails, which is why it often takes down a whole site at once. These are the usual reasons, roughly in order of how often they come up:

• An unhandled exception. Reading a property of undefined, parsing a cookie that is not valid JSON, or calling new URL() on a malformed value. Wrap risky parsing in try and catch.
• A missing environment variable. A variable set locally in .env.local but not added in the Vercel project settings for Production. Check Settings, then Environment Variables, and redeploy after adding it, because values are read at build and deploy time.
• An API the runtime does not support. Middleware has traditionally run on the Edge runtime, which has no fs, no native modules and only part of the Node.js API. Importing a database driver or an authentication library built for Node is a common trigger. Newer Next.js versions can run middleware on the Node.js runtime, and the Next.js 16 proxy.js file uses it by default, but check what your version does.
• A failing or slow fetch. Calling an external API in middleware on every request. If it rejects without a catch, the invocation fails; if it hangs, you get a timeout instead (MIDDLEWARE_INVOCATION_TIMEOUT, a 504).
• A redirect loop or bad rewrite. Middleware that redirects /login to /login, or rewrites to a URL that runs the same middleware again.

Once the cause is fixed, redeploy and test a few paths with curl -sI. Our 500 errors guide covers the general server-side checks, and Server error (5xx) in Search Console explains what Google does if the outage lasted long enough to be crawled.

A worked example

Example Bakery runs a Next.js 15 shop on Vercel. Two things go wrong after a redesign: deleted cake pages still show in Google, and on Monday morning the whole site shows 500: INTERNAL_SERVER_ERROR, Code: MIDDLEWARE_INVOCATION_FAILED.

For the cakes, curl -sI https://www.example.com/cakes/lemon-drizzle returns HTTP/2 200. The page template shows Sorry, this cake is no longer available when the database returns nothing, but never calls notFound(). Google has kept 140 of these URLs as thin pages. The fix is two lines: import notFound and call it when the lookup is empty, in both the page and generateMetadata. After deploying, curl returns HTTP/2 404 and the URL Inspection live test in Search Console reports the 404.

For the outage, the Vercel logs for the middleware show TypeError: Cannot read properties of undefined (reading 'split'). The middleware reads a BASIC_AUTH variable to protect a staging path, and that variable was added only to the Preview environment. On Production it is undefined, so .split(':') throws on every request. The developer adds the variable to Production, changes the code to skip the check when the value is missing, narrows the matcher to /staging/:path*, and redeploys. The site recovers within a minute, and the next deploy can no longer take it down for the same reason.

The fix, step by step

Edge cases worth knowing

• Streamed 404s. If you need a true 404 status from a page that uses Suspense, do the existence check before any Suspense boundary, or in generateMetadata. Otherwise you get a 200 with a noindex tag, which keeps the page out of the index but is still a soft 404.
• Nested not-found files. A not-found.js inside a segment only shows for notFound() calls in that segment. Unmatched URLs always use the root one.
• Static export. With output: 'export' there is no server, so the host decides the status. Configure it to serve 404.html with a 404 status, for example with an nginx error_page rule.
• Redirect instead of 404. Redirecting every missing URL to the home page is treated by Google as a soft 404. Redirect only when there is a genuine replacement, as covered in how to set up a 301 redirect.
• Errors in event handlers. Error boundaries do not catch errors in click handlers or timers. Handle those with try and catch in the handler.
• Self-hosting. Behind nginx or another proxy, check that the proxy passes Next.js status codes through and does not replace 404 and 500 responses with its own pages.

Keeping your error pages correct

Error handling breaks quietly, usually during a refactor, so add checks that run without you remembering. A short script in your deploy pipeline that requests a known missing URL and fails the build if it does not get a 404 catches most regressions:

status=$(curl -s -o /dev/null -w "%{http_code}" https://preview.example.com/this-page-does-not-exist)
[ "$status" = "404" ] || { echo "Expected 404, got $status"; exit 1; }

• Keep every Production environment variable that middleware needs listed in your README, and check them before each release.
• Send middleware and error.js logs to a monitoring service so you hear about failures before your visitors do.
• Re-crawl the site after major changes and look for 200 responses on pages that should be gone, and 5xx responses anywhere. The HTTP error audit guide explains how to read the results.
• Watch the Pages report in Search Console for Soft 404 and Server error (5xx) entries after each launch.

For the wider picture of how Next.js sites get crawled and indexed, see Next.js SEO fixes.