· By John Kavanagh

Following a Next.js Server Error Back to the Request

Photograph of railway tracks meeting at a set of points amongst trees.
Image by Christopher Beddies, licensed from Unsplash.

A production error page tells us that the catalogue couldn't be loaded. Next has supplied an error digest, so we have something to search for. What we still need is a server record which explains where that error occurred and which request encountered it.

Logging the browser's error.message again doesn't necessarily provide that explanation. When a Server Component fails in production, Next deliberately sends a generic message to the client. The useful detail belongs on the server, with an appropriate route back to it.

Next 15's onRequestError hook gives us that point of integration. My example uses an App Router page which deliberately throws, then follows the production response back to a small server‑side report. I also make the same page fail twice. The repeated error is where the distinction between a digest and a request ID becomes useful.


Keep the Production Error Private

The browser should be able to explain that something failed without receiving a database error, an internal URL, or whatever happened to be included in a server exception.

Next's error‑file documentation describes that production behaviour: a Server Component error reaches the client with a generic message and a digest. Development is deliberately more helpful with the original message, so checking only the development overlay would give us the wrong expectation.

My error.tsx displays a plain explanation, the digest, and a link back to the example. It also records the error object received by the client, so I can inspect the difference without treating a screenshot of the fallback as sufficient evidence.

I covered the role of fallback UI in my React error‑boundaries article. Here the additional job is connecting that UI to the server failure. A useful fallback and a useful diagnostic record solve different parts of the problem.


Report the Error Where Next Captures It

The instrumentation hook receives the captured error, request information, and framework context. The context identifies the route and whether the error arose during rendering, a Route Handler, or another supported operation.

In instrumentation.ts, my Node‑side integration is:

import type { Instrumentation } from 'next';

export const onRequestError: Instrumentation.onRequestError = async (
  error,
  request,
  context,
) => {
  if (process.env.NEXT_RUNTIME === 'nodejs') {
    const { reportRequestError } = await import('./reporter');
    await reportRequestError(error, request, context);
  }
};

The runtime check belongs around the import as well as the work. My reporter writes to a local file using Node's filesystem API; that dependency doesn't belong in an Edge bundle. The downloadable example also has a switch which disables this report so I can compare the client‑only result.

I await the reporter. Starting an asynchronous request to a logging service and immediately returning would leave its completion uncertain. With a remote collector, I would also give the operation a deadline and decide what happens when reporting fails. An error reporter should not make the failed request wait indefinitely for a second broken service.

The error passed to this hook may have been processed by React. I inspect its available fields rather than assuming it is still a particular application error class.


Give the Request Its Own Identifier

A digest is derived from the error. It isn't a unique receipt for the HTTP request.

Two requests can encounter the same failure and receive the same digest. That is useful when grouping errors, but insufficient when a colleague asks which of two attempts produced a particular response. I want a separate identifier for each accepted request, alongside the release and route.

For this example, Middleware creates an internal ID and overwrites the corresponding incoming header:

const requestId = crypto.randomUUID();
const headers = new Headers(request.headers);
headers.set('x-lab-request-id', requestId);

const response = NextResponse.next({ request: { headers } });
response.headers.set('x-lab-request-id', requestId);
return response;

The forwarded request header reaches the server hook. The response header gives me the same value in the browser's network inspector. I keep it separate from the digest shown by the error boundary.

This header is my example's correlation convention. It doesn't authenticate a visitor or authorise an operation. Nor do I accept a caller's chosen value as my internal ID: two callers are quite capable of sending the same tidy‑looking UUID.

The test sends two overlapping requests with the same forged incoming ID. Their response IDs must differ from that value and from each other. Their server records then show which request encountered the repeated digest. I don't expect that digest to remain unchanged after a different release changes the generated code.


Choose the Fields Before Serialising Anything

It would be convenient to send the entire request and error objects to a collector. It would also be a convenient way to make that collector a second home for session cookies and private query parameters.

My reporter selects a small record after checking the request ID and digest values:

const record = {
  requestId,
  digest,
  release: process.env.LAB_RELEASE,
  method: request.method,
  route: context.routePath,
  router: context.routerKind,
  kind: context.routeType,
  renderSource: context.renderSource ?? null,
};

I use the framework's route description rather than the raw requested URL, which may contain a query string. The record excludes headers, cookies, the request body, and the error's arbitrary message and stack. Those are deliberate choices for this example, not a claim that every production logging system needs the same eight fields.

A more detailed reporter needs its own rules for the additional data. Error messages deserve particular attention: application code can put private information in them just as easily as in an ordinary log statement.

The fixture sends a synthetic private marker through a cookie, an authorisation header, a query parameter, and a POST body. It then checks the saved records for that marker. Keeping the test input fake lets me exercise the omission without creating the problem I'm trying to prevent.


Check the Hook with a Real Failed Request

My working example builds the application and runs the production server. The browser must show the fallback and receive the generic error message. Its digest must match a saved server event carrying that response's request ID.

I also request the throwing Route Handler. Its record should identify a route operation and POST, rather than pretending every error came from rendering a component. The test checks actual framework context; it doesn't call my reporter directly and assume Next will supply the same arguments.

With server reporting disabled, the browser still receives its digest, but my custom server report is empty. With the local collector made to fail, the request still completes and a short warning is written without dumping the rejected record. Those controls tell me what the integration adds and what happens when it cannot do its job.


Wrapping Up

The digest helps me find the error. The request ID, release, and route help me understand a particular occurrence of it.

I want those values connected before I need to investigate a real failure. A production request through the actual hook, followed back to a deliberately small report, is a useful way to check that connection without exposing the request itself.

Postscript

November 2026: I've added my production request‑error example for Next 15.3.1 and Next 16.4.6. It compares repeated failures, client‑only reporting, and a failed collector, including checks that private request fields stay out of the saved reports. The current version uses proxy.ts for the request ID step; the article's middleware.ts name belongs to the Next 15 version. Both lockfiles were prepared for this update, using the framework versions stated in the README.

Downloadable Resource

  • Next.js Request Error Correlation

    Follow my production error examples from a browser digest to the matching Next.js server report. Compare request IDs, private fields, and reporter failures.

    Download ZIP

Want to find out more?

If you need senior hands‑on support with a complex React or Next.js platform, migration, performance issue, or technical SEO problem, send me the context and I'll tell you where I can help.