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 seeWhere it happenedWhere to look
“A server-side exception has occurred” + DigestServer (Server Component, Server Action, route handler)Server logs, searched by digest
“A client-side exception has occurred”BrowserBrowser console and client error reports, with source maps
Page renders, then flickers or warns about a mismatchHydration (server and client HTML differ)Compare server output vs client render
500 from an API route with no UI errorRoute handler or something it callsServer logs and traces for that route
Redirect loop or blank page before renderMiddlewareMiddleware 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:

  1. Tag every build with a version. Set service.version to your Git SHA in CI (see the naming step in our OpenTelemetry guide).
  2. Check when the error first appeared. If the first occurrence matches a deploy, start with that deploy’s diff.
  3. 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

ErrorUsual causeQuick check
Hydration mismatchServer and client render different HTML: dates, Math.random(), window checks, browser extensionsLook for anything time-, locale- or browser-dependent in the component
Digest error in a Server ComponentAn exception during server rendering, often a failed fetch or a database callSearch server logs for the digest
fetch failed / timeout in a server renderUpstream API slow or down, or a missing environment variable for its URLCheck the trace for the slow span; check env vars on the running pod
“Dynamic server usage” errorA page treated as static uses cookies(), headers() or search paramsMark the route dynamic, or move that logic
Works locally, fails on EdgeCode uses a Node.js-only API in middleware or an Edge routeCheck 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.ts with OpenTelemetry tracing and an onRequestError hook
  • Structured JSON logs with trace_id, shipped somewhere that outlives your pods
  • Source maps generated and uploaded privately
  • error.tsx boundaries on key routes, plus global-error.tsx
  • service.version set 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