Next.js "An error occurred in the Server Components render": Finding the Real Error Behind the Digest
Next.js error digest explained: why production hides Server Component errors, how to match the digest to your server logs, and the usual root causes.
In production, Next.js and React hide the message of any error thrown on the server, so secrets and internal details don't leak to the browser. What you see instead is a generic message plus a digest, a short hash that identifies the original error. The real error, with its message and stack trace, is in your server logs, and the digest is how you find it there. The bug itself is almost always ordinary: a missing environment variable, a database that refuses the connection, or a fetch that failed.
Checked against the Next.js docs for error.js, error handling and instrumentation, the React and Next.js source on GitHub, and Vercel's runtime logs docs in November 2026 (Next.js 16.4).
What the error looks like
In the browser console:
Error: An error occurred in the Server Components render. The specific message is omitted in production builds to avoid leaking sensitive details. A digest property is included on this error instance which may provide additional details about the nature of the error.
On the page, if you have no error boundary of your own, Next.js shows its built-in error screen. In Next.js 16.2 and later it reads "This page couldn't load" and "A server error occurred. Reload to try again.", with ERROR 1234567890 in small print at the bottom. Older versions show:
Application error: a server-side exception has occurred (see the server logs for more information).
Digest: 1234567890
Both point at the same thing. That number is the digest.
What the digest is
When a Server Component, Server Action or route render throws, Next.js computes a digest from the error's message and stack (a numeric string hash) and attaches it to the error. Then:
- On the server, the original error is logged in full, with the digest attached.
- On the client, the error that reaches your error boundary carries only the generic message and the same
digest.
The Next.js docs put it plainly: errors forwarded from Server Components "show a generic message with an identifier", and error.digest "can be used to match the corresponding error in server-side logs."
During next dev you get the full message in the browser, which is why the bug often seems to appear only after deploying. Run the production build locally to see the same behaviour:
npm run build && npm start
Reproduce the failure, and the full error appears in that terminal.
A few digests are readable words instead of numbers. Next.js uses fixed digests for its own control-flow errors, for example NEXT_REDIRECT for redirect() and DYNAMIC_SERVER_USAGE when a route that Next.js tried to render statically uses cookies() or headers(). If you see one of those, the problem is in how that API is called, not in your data.
Step 1: find the real error in the server logs
Copy the digest from the page or the console, then search your server logs for it. Where those logs live depends on how you host:
| Hosting | Where to look |
|---|---|
next start on your own server |
The process's stdout/stderr: journalctl -u your-service, pm2 logs, or wherever your process manager writes |
| Docker | docker logs <container> (or docker compose logs app) |
| Vercel | Project, then Logs in the sidebar (runtime logs), or vercel logs --environment production --query 'level:error' |
| Other platforms | The runtime or function logs, not the build logs |
Two things catch people out:
- Build logs are not runtime logs. The error happens when a request is served, so it's in the runtime output.
- Retention can be short. Vercel's docs list one hour of runtime logs on the Hobby plan and one day on Pro. Reproduce the error, then look straight away.
Once you find the log entry with your digest, you have the real message and stack trace, and the rest is normal debugging.
Step 2: check the usual root causes
These cover most production-only digest errors.
A server environment variable is missing in production
Your .env.local isn't deployed. If a Server Component reads process.env.DATABASE_URL or an API key and the hosting environment doesn't set it, the code throws (or a client library throws on an undefined key). Set the variable in your host's environment settings and restart or redeploy.
Variables prefixed with NEXT_PUBLIC_ are different: they are inlined into the browser bundle at build time, so changing them requires a rebuild. Why is my environment variable undefined? covers both cases.
The database connection fails
The database URL points at localhost, the production database requires SSL, the IP isn't allowed through the database's firewall, or the connection pool is exhausted. The server log will show the driver's error (ECONNREFUSED, a TLS error, "too many connections"). Fix the connection string or network rules rather than the page.
A fetch in a Server Component fails
Common versions:
- Fetching your own API with a relative URL (
fetch('/api/posts')). On the server there is no current origin, so use an absolute URL or, better, call the underlying function directly instead of going through HTTP. - The upstream API returned an error page and
res.json()threw on HTML. - An auth header or API key that exists locally isn't set in production.
Code that assumes data exists
post.title when post is null throws on the server just as it would in the browser. Check for missing data and call notFound() instead of letting the render crash.
Step 3: handle errors properly with error.tsx and global-error.tsx
An error boundary doesn't fix the bug, but it decides what users see and gives you the digest to report.
error.tsx wraps a route segment and its children. It must be a Client Component:
// app/dashboard/error.tsx
'use client'
import { useEffect } from 'react'
export default function Error({
error,
retry,
}: {
error: unknown
retry: () => void
}) {
const digest =
error instanceof Error && 'digest' in error ? String(error.digest) : undefined
useEffect(() => {
console.error(error)
}, [error])
return (
<div>
<h2>Something went wrong.</h2>
{digest && <p>Reference: {digest}</p>}
<button onClick={() => retry()}>Try again</button>
</div>
)
}
Showing the digest as a reference code is useful: when a user reports a problem, you can search your logs for exactly that error.
Version notes: retry was added as unstable_retry in 16.2 and became stable in 16.3. On older versions the prop is reset, and the typical type for error is Error & { digest?: string }.
error.tsx does not catch errors in the root layout. For that, add app/global-error.tsx, which replaces the root layout when it renders and so must include its own <html> and <body> tags.
For more on how boundaries work, see React error boundaries.
Expected errors shouldn't throw at all
The Next.js docs separate expected errors (validation failures, a failed request you can recover from) from uncaught exceptions. For expected errors in Server Functions, return a value such as { message: 'Failed to create post' } and show it with useActionState. In a Server Component, check res.ok and render a message. Reserve throwing for real bugs, and your error boundaries stay meaningful.
Step 4: report server errors with onRequestError
Searching logs by hand works for one bug. For a running app, send every server error somewhere searchable. Since Next.js 15, instrumentation.ts can export an onRequestError hook that runs whenever the server captures an error:
// instrumentation.ts (project root, or src/)
import { type Instrumentation } from 'next'
export const onRequestError: Instrumentation.onRequestError = async (
err,
request,
context
) => {
const message = err instanceof Error ? err.message : String(err)
const digest =
typeof err === 'object' && err !== null && 'digest' in err
? String(err.digest)
: undefined
await fetch(process.env.ERROR_WEBHOOK_URL!, {
method: 'POST',
headers: { 'Content-Type': 'application/json' },
body: JSON.stringify({
message,
digest,
path: request.path,
method: request.method,
route: context.routePath,
routeType: context.routeType, // 'render' | 'route' | 'action' | 'proxy'
}),
})
}
This runs on the server, so it sees the real message alongside the digest. Await any async work inside it, as the docs advise. Error monitoring services use this hook too (Sentry's Next.js setup exports onRequestError = Sentry.captureRequestError); error monitoring for beginners covers choosing one.
Be careful what you forward. request.headers can include cookies and authorization tokens, so don't ship the whole object to a third party.
Quick checklist
- Copy the digest from the page or browser console.
- Search the runtime logs for it (or reproduce with
npm run build && npm startand watch the terminal). - Read the real error: usually a missing env var, a database connection or a failed fetch.
- Fix the cause, then redeploy (rebuild if a
NEXT_PUBLIC_variable changed). - Add
error.tsxandglobal-error.tsxthat show the digest as a reference. - Add
onRequestErrorso the next one reaches you without digging.
If the production-only bug turns out to be a mismatch between server and client HTML instead, that's a hydration error, which has different causes.
On EasySpawn, the Next.js app runs on the same persistent server as Claude Code, so the agent can read the server's runtime logs, find the line with your digest and fix the cause in the same session. See how it works or join the waitlist.
Related: Next.js Hydration Errors: What They Mean and How to Fix Them · React Error Boundaries: Stop One Broken Component Crashing the Page · Why Is My Environment Variable Undefined? (Vite, Next.js, Node) · Self-Hosting Next.js Without Vercel: What Works, What Breaks, What to Configure
Keep reading
Vite "Error while updating dependencies", "The file does not exist at .vite/deps" and "504 (Outdated Optimize Dep)": Causes and Fixes
Vite "error while updating dependencies" and 504 Outdated Optimize Dep explained: what dependency pre-bundling is, why its cache goes stale, and fixes in order.
React Error Boundaries: Stop One Broken Component Crashing the Page
Without an error boundary, one component throwing during render blanks your entire React app. How error boundaries work, using react-error-boundary with fallbacks and reset, Next.js error.tsx and global-error.tsx, what boundaries don't catch, and reporting errors to monitoring.