Next.js shows Application error: a client-side exception has occurred
Application 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.
Fix it fast
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 open2Match what you see, then jump to its fix
- 1
The console shows a normal error such as TypeError with a file and line from your code.A Client Component throws while renderingFix - 2
The console message is generic and carries a digest value.An error from a Server Component, shown only as a digestFix - 3
The 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
The 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
- 1
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 line2Fix
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 startConfirmed by react.dev
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/logs2Fix
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 startConfirmed by nextjs.org
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/null2Fix
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 build3Verify
Start the new build and open the page that crashed.
npx next startConfirmed by nextjs.org
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.tsx2Fix
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 startConfirmed by react.dev
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:
- TaxiDexMy own multi-tenant taxi dispatch SaaS: API, dispatcher portal, driver and passenger apps, and the servers underneath.
- QistLockA NestJS and React SaaS driving an Android Device Owner agent that locks financed phones when payments lapse.
- TaskvareA task and project-management suite: React on the web, Flutter on mobile, TypeScript underneath.
Related fixes
Web apps
Next.js: Event handlers cannot be passed to Client Component props
onClick in a Server Component, or a callback prop sent to a Client Component
In the App Router, pages and layouts are Server Components, and a function cannot be sent from the server to the browser as a prop.
3 causes, each with a fixWeb apps
A Next.js environment variable is undefined in the browser or after deploy
TypeError: Cannot read properties of undefined
Next.js only gives the browser variables whose names start with NEXT_PUBLIC_, and it copies their values into the JavaScript at build time.
4 causes, each with a fixWeb apps
ESLint says an element in a list is missing its key prop
react/jsx-key
react/jsx-key fires when an element returned from map, Array.from or an array literal has no key.
3 causes, each with a fixWeb apps
There is no tailwind.config.js after installing Tailwind 4 and HeroUI in Next.js
HeroUI components render unstyled
Nothing is broken: Tailwind CSS 4 is configured in CSS and no longer creates tailwind.config.js.
3 causes, each with a fixWeb apps
react-i18next shows the wrong plural form for a count, or prints the key instead of the text
t('item') prints the key item instead of a translated sentence
i18next picks a plural from the count option and looks for keys ending in _one, _other and so on.
4 causes, each with a fixWeb apps
useSession throws because there is no SessionProvider above it
[next-auth]: `useSession` must be wrapped in a <SessionProvider />
useSession reads the session from React Context, and SessionProvider is what creates that context.
3 causes, each with a fix