Maaz Zindani

Loading the index…

↑↓ move↵ openesc close4072 pages
Next.js and React

Next.js shows Application error: a client-side exception has occurred

ErrorApplication error: a client-side exception has occurred (see the browser console for more information).

Short answer

This white page is Next.js's fallback when an uncaught error unmounts the React tree, and it hides the real message. Open the browser console for the original error. If the console only shows a digest, search the server logs for it. Then add an error boundary so one broken component does not blank the page.

  • Applies to Next.js 15, Next.js 16, React 19
  • Updated
  • By Maaz Zindani, Senior Software Engineer

Fix it fast

  1. 1Find out which cause you have

    Reproduce the page with DevTools open and read the first red error in the console. If the message is a generic one with a digest value, the error was thrown on the server and the details are in the server logs, not in the browser.

    # production-like run on your machine, so the console shows the real error
    npx next build && npx next start
    # then open the page with DevTools > Console open
  2. 2Match what you see, then jump to its fix

    1. 1The console shows a normal error such as TypeError with a file and line from your code.A Client Component throws while renderingFix
    2. 2The console message is generic and carries a digest value.An error from a Server Component, shown only as a digestFix
    3. 3The stack points to code that reads process.env.NEXT_PUBLIC_..., and only the deployed build fails.A NEXT_PUBLIC_ value was missing when the app was builtFix
    4. 4The error appears right after a file got a 'use client' line, or after a function or class instance was passed as a prop.Server-only code or a non-serializable prop crosses into a Client ComponentFix

What does the error look like?

  • Application error: a client-side exception has occurred (see the browser console for more information).
  • An error in production with a digest and no readable message

Cause 1 of 4

A Client Component throws while rendering

1Check

By default, when your app throws during rendering, React removes its UI from the screen. Without an error boundary, the whole page goes blank. Errors from Client Components keep their original message.

# read the stack in the console, then open that file at that line

2Fix

Fix the line named in the stack, usually a value that is undefined when the component first renders. Add an error.js file for the route segment so a failure shows a fallback and not a blank page.

// app/dashboard/error.tsx
'use client'

export default function Error({ reset }: { reset: () => void }) {
  return (
    <div>
      <h2>Something went wrong</h2>
      <button onClick={() => reset()}>Try again</button>
    </div>
  )
}

3Verify

Reload the route. The crash is fixed, or the fallback shows and the rest of the layout stays visible.

npx next build && npx next start

Confirmed by react.dev

Did this fix it?

Cause 2 of 4

An error from a Server Component, shown only as a digest

1Check

In production, errors from Server Components are replaced with a generic message and an identifier, so details are not leaked. The identifier is error.digest, and it matches a line in the server logs.

# on the server, search the app's log output for the digest from the browser
grep -r "DIGEST_VALUE" /path/to/app/logs

2Fix

Read the matching server log entry and fix the failing fetch or data access. Log error.digest in your error.js so you can search for it.

'use client'
import { useEffect } from 'react'

export default function Error({ error }: { error: unknown }) {
  useEffect(() => {
    console.error(error instanceof Error ? (error as Error & { digest?: string }).digest : error)
  }, [error])
  return <h2>Something went wrong</h2>
}

3Verify

Trigger the failure again. The log line, the digest and the fix agree.

npx next start

Confirmed by nextjs.org

Did this fix it?

Cause 3 of 4

A NEXT_PUBLIC_ value was missing when the app was built

1Check

NEXT_PUBLIC_ values are copied into the JavaScript during next build. If the variable was not set in the environment of the build, the browser code gets nothing for it.

env | grep NEXT_PUBLIC_
grep -rn "NEXT_PUBLIC_" app src components lib 2>/dev/null

2Fix

Set the variable in the build environment and rebuild. Changing it on a running server does not update the bundle.

NEXT_PUBLIC_API_URL=https://api.example.com npx next build

3Verify

Start the new build and open the page that crashed.

npx next start

Confirmed by nextjs.org

Did this fix it?

Cause 4 of 4

Server-only code or a non-serializable prop crosses into a Client Component

1Check

Props from a Server Component to a Client Component must be serializable: plain objects, arrays, strings, numbers, dates, promises, JSX and Server Functions. 'use client' must be at the very top of the file, above imports.

head -3 app/ui/the-component.tsx

2Fix

Pass plain data only, keep database or secret-using code in server files, and leave 'use client' off modules that were written for the server.

// server side
const row = await getUser(id)
return <Profile name={row.name} createdAt={row.createdAt.toISOString()} />

3Verify

Load the page again with the console open. No error is shown.

npx next build && npx next start

Confirmed by react.dev

Did this fix it?

How do I stop it coming back?

  • Add error.js to each major route segment so a failure shows a fallback.
  • Log error.digest from the error boundary and keep server logs searchable.
  • Test the production build locally before deploying; do not rely on next dev.
  • Pass plain, serializable data from Server to Client Components.

Sources

How was this page made?

I drafted this page with AI assistance from the official documents listed under Sources. Every cause above names the document that confirms it. I have not reproduced this fix on a machine of my own yet, so read it as documented guidance, not a test report. Found a mistake? Tell me.

Which stack is behind this page?

Projects of mine built on the same technologies:

Related fixes

Next step

Want this handled for good?

I look after servers, apps and releases end to end. Tell me what keeps breaking.