How to Debug a Production Error in Next.js: A Step-by-Step Playbook
Production Next.js errors hide behind a digest, minified stack traces and two runtimes. Here's a step-by-step playbook to go from 'something broke' to root cause, with copy-paste code.
By Hiren Patel, Founder & CEO · · 9 min read
It works on your machine. It works in staging. Then a customer sends a screenshot from production that says:
Application error: a server-side exception has occurred (see the server logs for more information). Digest: 2417831906
No message, no stack trace, no line number, just a digest.
Debugging Next.js in production is harder than debugging most Node.js apps. Code runs in two places (server and browser), sometimes on two runtimes (Node.js and Edge), and production builds deliberately hide error details from users. This playbook walks through how to go from “something broke” to the actual root cause, step by step, and how to set things up so the next one takes minutes.
Why production Next.js errors are hard to read
Three things work against you:
1. Server errors are hidden on purpose. In production, when a Server Component or Server Action throws, Next.js doesn’t send the real error message to the browser, because it could leak secrets or internals. The client gets a generic message and a digest: a hash that identifies the error. The full error is only in your server logs.
2. Browser code is minified. Client-side stack traces point at things like page-8f3a2c.js:1:48213. Without source maps, they’re almost useless.
3. One request touches many layers. A single page load can involve middleware, a Server Component, a fetch to your API, a database call, and then client-side hydration. The error might show up in one layer and be caused in another.
The playbook
Step 1: Work out which side it happened on
Before searching anything, classify the error. It decides where you look next.
| What you see | Where it happened | Where to look |
|---|---|---|
“A server-side exception has occurred” + Digest | Server (Server Component, Server Action, route handler) | Server logs, searched by digest |
| “A client-side exception has occurred” | Browser | Browser console and client error reports, with source maps |
| Page renders, then flickers or warns about a mismatch | Hydration (server and client HTML differ) | Compare server output vs client render |
500 from an API route with no UI error | Route handler or something it calls | Server logs and traces for that route |
| Redirect loop or blank page before render | Middleware | Middleware logs (often Edge runtime) |
Step 2: Turn the digest into the real error
The digest isn’t random. Next.js logs the full server error with the same digest. Search your server logs for that number:
# Kubernetes example
kubectl logs deploy/web-frontend --since=1h | grep 2417831906
You’ll find the real message and stack trace there.
If nothing comes back, the error was logged by a pod that has since been replaced, or your logs aren’t being kept. That’s the first fix to make: server logs need to outlive pods. Ship them somewhere searchable (Step 6 covers how).
Step 3: Capture every server error with onRequestError
Searching logs by hand works once. To catch every server error with context, Next.js (version 15 and later) lets you export an onRequestError hook from the same instrumentation.ts file used for OpenTelemetry. It’s called whenever the server catches an error while handling a request.
// instrumentation.ts
import { registerOTel } from '@vercel/otel';
import type { Instrumentation } from 'next';
export function register() {
registerOTel({ serviceName: process.env.OTEL_SERVICE_NAME ?? 'web-frontend' });
}
export const onRequestError: Instrumentation.onRequestError = async (
err,
request,
context
) => {
const error = err as Error & { digest?: string };
console.error(
JSON.stringify({
level: 'error',
msg: error.message,
digest: error.digest,
stack: error.stack,
path: request.path,
method: request.method,
routePath: context.routePath, // e.g. /checkout/[id]
routeType: context.routeType, // 'render' | 'route' | 'action' | 'middleware'
routerKind: context.routerKind, // 'App Router' | 'Pages Router'
})
);
};
Every server error now produces one structured log line with the digest, the route pattern, and what kind of work was happening. Combined with the OpenTelemetry setup from our OpenTelemetry guide for Next.js and Node.js, that log line also carries the trace_id of the request, so you can jump straight to the full trace.
Note: Don’t log full request headers. They contain cookies and authorization tokens. Log the path, method and route, and scrub anything sensitive in your OpenTelemetry Collector.
Step 4: Make client-side stack traces readable
For browser errors, you need source maps. You have two options:
Option A: Upload source maps privately (recommended). Generate them during the build, upload them to your error-tracking tool, and don’t serve them publicly. Your tool turns page-8f3a2c.js:1:48213 back into CheckoutForm.tsx:42.
Option B: Serve them publicly. Simple, but anyone can then read your original frontend source.
// next.config.js
module.exports = {
productionBrowserSourceMaps: true, // generates .map files for client bundles
};
If you choose Option A, make sure your deploy step removes the .map files from the public output after uploading them.
Then catch client errors where they happen, using App Router error boundaries:
// app/checkout/error.tsx
'use client';
import { useEffect } from 'react';
export default function CheckoutError({
error,
reset,
}: {
error: Error & { digest?: string };
reset: () => void;
}) {
useEffect(() => {
// Send to your error tracking here. Include the digest for server errors.
console.error('checkout error', { message: error.message, digest: error.digest });
}, [error]);
return (
<div>
<h2>Something went wrong with checkout.</h2>
<button onClick={() => reset()}>Try again</button>
</div>
);
}
Add an app/global-error.tsx too. It catches errors in the root layout, which a normal error.tsx can’t.
Step 5: Reproduce what the user actually did
You now have the real error and stack trace. The next question is usually: how did the user get here?
Stack traces show where the code failed, not why this user hit it when thousands of others didn’t. Common culprits:
- A specific input (an empty cart, a very long name, a missing optional field)
- A specific sequence (back button after submit, two tabs open, a double-click)
- A specific environment (an old browser, a slow network that triggers a timeout path)
- A feature flag or A/B variant only some users see
This is where session replay earns its place. Seeing the 30 seconds before the error, what was clicked, what was typed, and which requests failed, often answers in one view what would otherwise take an hour of guessing. If you don’t have replay, at least log the route, the user’s plan or segment (not their identity), the app version, and any active feature flags with every error.
Step 6: Find what changed
Most production errors are caused by a change: a deploy, a dependency upgrade, a config change, or a change in an upstream API.
Make this question instant to answer:
- Tag every build with a version. Set
service.versionto your Git SHA in CI (see the naming step in our OpenTelemetry guide). - Check when the error first appeared. If the first occurrence matches a deploy, start with that deploy’s diff.
- Read the diff for the file in the stack trace.
git log -p --since="2 days ago" -- app/checkout/is often faster than any dashboard.
Step 7: Fix, then prove it’s fixed
Once you’ve shipped the fix, check that the error rate for that digest or error signature actually drops to zero on the new version. “We deployed a fix” and “the error stopped” are different statements. Only the second one closes the incident.
The five errors you’ll see most often
| Error | Usual cause | Quick check |
|---|---|---|
| Hydration mismatch | Server and client render different HTML: dates, Math.random(), window checks, browser extensions | Look for anything time-, locale- or browser-dependent in the component |
| Digest error in a Server Component | An exception during server rendering, often a failed fetch or a database call | Search server logs for the digest |
fetch failed / timeout in a server render | Upstream API slow or down, or a missing environment variable for its URL | Check the trace for the slow span; check env vars on the running pod |
| “Dynamic server usage” error | A page treated as static uses cookies(), headers() or search params | Mark the route dynamic, or move that logic |
| Works locally, fails on Edge | Code uses a Node.js-only API in middleware or an Edge route | Check the runtime; move the code to the Node.js runtime if needed |
Set it up once, so the next error takes minutes
If you take one thing from this post, make it this setup checklist:
-
instrumentation.tswith OpenTelemetry tracing and anonRequestErrorhook - Structured JSON logs with
trace_id, shipped somewhere that outlives your pods - Source maps generated and uploaded privately
-
error.tsxboundaries on key routes, plusglobal-error.tsx -
service.versionset to your Git SHA on every build - Session replay, or at least route, version and feature flags on every error
With this in place, Steps 2 to 6 stop being a hunt across tabs and become one search.
How Modulis handles this
Modulis connects these pieces for you, inside your own cloud. When a Next.js error happens, you see the error with its readable stack trace, the server or client trace it came from, the logs around it, the user’s session leading up to it, and the GitHub commit that last changed that code path, all in one view.
Setup is low-friction: Modulis opens a pull request that adds the SDK to your Next.js app. You review it, merge, deploy, and data typically starts flowing in under 30 minutes. Everything runs in your own cloud, and AI-assisted analysis uses your own LLM key, so your code and telemetry never leave your environment.
Next time you see a digest, you’ll know where to look. Start free to have it all in one place, or book a 20-minute walkthrough.
See the error, the trace, the logs and the session together
Modulis runs in your own cloud and connects every Next.js error to the request, logs, user session and commit behind it. Start free.
Related posts
What One Production Incident Really Costs You (With a Calculator)
Most incident cost isn't the fix. It's the hours engineers spend gathering context across tools. Here's a phase-by-phase breakdown and a calculator you can run with your own numbers.
· 8 min read
Before You Turn On an AI SRE Agent: Where Your Code and Logs Actually Go
AI root-cause agents need your stack traces, logs and source code to work. Here's the data path most vendors don't draw for you, 12 questions to ask before you enable one, and what it means for SOC 2, HIPAA and GDPR.
· 7 min read
Why Your Monitoring Bill Grows Faster Than Your Traffic
Your services grew 4x. Your monitoring bill grew 5x. Here's the compounding math behind per-host, per-GB and custom-metric pricing — and a checklist to cut spend this week.
· 8 min read