A custom error from the server arrives at the client as a generic message
error.message is a generic text in production but the real message in developmentShort answer
Next.js hides the message of errors thrown in Server Components in production, to avoid leaking details. The client gets a generic message and an error.digest hash. Look the digest up in your server logs. For errors you expect, such as validation, return them as values from a Server Function instead of throwing.
Fix it fast
1Find out which cause you have
Build and run the app in production mode locally. The hidden message only appears there, so this reproduces it without waiting for a deploy.
npm run build && npm run start2Match what you see, then jump to its fix
- 1
error.message shows a generic text and a digest identifierErrors from Server Components are sanitized on purposeFix - 2
Invalid input or a failed API call is reported by throw, and the form shows nothing usefulAn expected error is thrown from a Server FunctionFix - 3
error.tsx never shows, and a click that fails does nothing visibleThe error happens in an event handler, so no error boundary sees itFix
- 1
What does the error look like?
error.message is a generic text in production but the real message in developmenterror.digest holds a hash instead of your message
Cause 1 of 3
Errors from Server Components are sanitized on purpose
1Check
Errors forwarded from Server Components show a generic message with an identifier. Errors from Client Components keep their original message. Check which kind of component threw.
grep -rn "throw new" app lib2Fix
Log the real error on the server and use the digest to find it. In error.tsx, show a friendly text and the digest so users can quote it.
// app/dashboard/error.tsx
'use client'
export default function Error({ error }: { error: Error & { digest?: string } }) {
return (
<div>
<h2>Something went wrong</h2>
{error.digest && <p>Reference: {error.digest}</p>}
</div>
)
}3Verify
Trigger the failure in the production build, then search the server output for the same digest.
npm run start 2>&1 | grep -i "digest"Confirmed by nextjs.org
Cause 2 of 3
An expected error is thrown from a Server Function
1Check
Validation failures and failed requests are normal events, not bugs. The docs say to avoid try/catch and throw for them in Server Functions and to model them as return values.
grep -rn "use server" app lib2Fix
Return an object with the message from the action and read it with useActionState in the form.
// app/actions.ts
'use server'
export async function createPost(prevState: unknown, formData: FormData) {
const res = await fetch('https://api.example.com/posts', { method: 'POST' })
if (!res.ok) {
return { message: 'Failed to create post' }
}
}
// app/ui/form.tsx
'use client'
import { useActionState } from 'react'
const [state, formAction, pending] = useActionState(createPost, { message: '' })3Verify
Submit the form with bad input in the production build and confirm the message shows.
npm run build && npm run startConfirmed by nextjs.org
Cause 3 of 3
The error happens in an event handler, so no error boundary sees it
1Check
Error boundaries catch errors during rendering. Errors in event handlers or other async code run after rendering and are not caught by them.
grep -rn "onClick=" app components2Fix
Catch the error in the handler, store it in state and render a fallback from that state.
'use client'
import { useState } from 'react'
export function Button() {
const [error, setError] = useState<unknown>(null)
const handleClick = async () => {
try {
await doWork()
} catch (reason) {
setError(reason)
}
}
if (error) return <p>Could not finish. Try again.</p>
return <button onClick={handleClick}>Run</button>
}3Verify
Click the button with the backend failing and see the fallback text.
npm run devConfirmed by nextjs.org
How do I stop it coming back?
- Return expected errors as plain objects with a code and a message, not as thrown exceptions.
- Log every unexpected server error with its digest so support can match a user report to a log line.
- Test error screens against a production build, not only next dev.
- Never put secrets or internal paths in an error message you write.
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.
- WorkforceA field app, an admin console and a self-hosted Node.js server for push and reconciliation.
Related fixes
Web apps
Upgrading to Next.js 16: middleware becomes proxy, and the other things that break
Missing Required default.js for Parallel Route
Next.js 16 renames middleware.ts to proxy.ts and its exported function to proxy.
6 causes, each with a fixWeb apps
Warning: Extra attributes from the server in the console
Text content does not match server-rendered HTML
React found attributes on an element in the server HTML that its own render did not produce.
3 causes, each with a fixWeb apps
Next.js stops with 'document is not defined' while it renders on the server
ReferenceError: document is not defined
Next.js renders your components on the server first, where there is no document.
3 causes, each with a fixWeb apps
useState fails in a child component in the Next.js App Router
React client hook in Server Component
In the App Router every component is a Server Component unless a file above it is marked otherwise, and Server Components cannot use state or effects.
3 causes, each with a fixWeb apps
React warns about updating one component while another renders
To locate the bad setState() call inside `Child`, follow the stack trace
React renders must be pure.
4 causes, each with a fixWeb apps
React warns that a div is nested inside a p tag
Text content does not match server-rendered HTML
A p element may contain only phrasing content, and the HTML parser closes a paragraph as soon as a div, list or other block element starts.
3 causes, each with a fix