Maaz Zindani

Loading the index…

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

A custom error from the server arrives at the client as a generic message

Errorerror.message is a generic text in production but the real message in development

Short 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.

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

Fix it fast

  1. 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 start
  2. 2Match what you see, then jump to its fix

    1. 1error.message shows a generic text and a digest identifierErrors from Server Components are sanitized on purposeFix
    2. 2Invalid 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. 3error.tsx never shows, and a click that fails does nothing visibleThe error happens in an event handler, so no error boundary sees itFix

What does the error look like?

  • error.message is a generic text in production but the real message in development
  • error.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 lib

2Fix

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

Did this fix it?

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 lib

2Fix

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 start

Confirmed by nextjs.org

Did this fix it?

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 components

2Fix

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 dev

Confirmed by nextjs.org

Did this fix it?

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:

Related fixes

Web 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

Next step

Want this handled for good?

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