Next.js Error Handling

Show a fallback when the segment throws; retry() refetches it in Next.js 16.3 and later.

'use client';

export default function Error({
  error,
  retry,
}: {
  error: Error & { digest?: string };
  retry: () => void;
}) {
  return <button onClick={retry}>Try again</button>;
}

Log the digest to match a hidden production error with your server logs.

useEffect(() => {
  console.error(error.digest, error);
}, [error]);

Catch errors in the root layout; it must render its own html and body tags.

'use client';

export default function GlobalError() {
  return (
    <html>
      <body>
        <h1>Something went wrong</h1>
      </body>
    </html>
  );
}

Render a custom 404 page for unknown URLs across the whole app.

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

export default function NotFound() {
  return <Link href="/">Back to home</Link>;
}

Trigger the 404 page from a page when the requested data does not exist.

import { notFound } from 'next/navigation';

const post = await getPost(slug);
if (!post) notFound();

Add a not-found.tsx inside a folder to customize the message for that section.

app/
  not-found.tsx          // site-wide
  blog/
    not-found.tsx        // blog only
    [slug]/page.tsx

Return a message from a Server Action instead of throwing for bad input.

'use server';

export async function signUp(
  _prev: { error: string },
  form: FormData
) {
  const email = String(form.get('email') ?? '');
  if (!email.includes('@')) {
    return { error: 'Enter a valid email' };
  }
  await createUser(email);
  return { error: '' };
}

Read the returned error in a Client Component and show it beside the form.

'use client';
import { useActionState } from 'react';
import { signUp } from './actions';

export function Form() {
  const [state, action] = useActionState(signUp, {
    error: '',
  });
  return (
    <form action={action}>
      <input name="email" />
      <p>{state.error}</p>
    </form>
  );
}

Check the response status and show a message instead of crashing the page.

const res = await fetch(url);
if (!res.ok) {
  return <p>Could not load prices.</p>;
}

Throw from a Server Component to hand control to the nearest error boundary.

const post = await getPost(id);
if (!post.published) {
  throw new Error('Post is not published');
}

Wrap a risky call and return a safe fallback value when it fails.

async function getRate() {
  try {
    const res = await fetch(url);
    return (await res.json()).rate;
  } catch {
    return null;
  }
}

Report every server error from one place by exporting this from instrumentation.ts.

// instrumentation.ts
export async function onRequestError(
  err: unknown,
  request: { path: string }
) {
  await reportError(err, request.path);
}