How to achieve proper server side stack trace line numbers in Next.js?

Question

Our team is running fairly simple Next.js apps and are seeing incorrect line numbers in the stack traces at the console when we encounter problems in our code.

To take a trivial example, start with the create-next-app tutorial code found here. Then modify that handler function to throw an Error:

export default function handler(req, res) {
  throw new Error("line2");
  res.status(200).json({ text: 'Hello' })
}

the ./pages/api/hello.js

Then visit http://localhost:3000/api/hello

At the console we are seeing:

Error: line2
    at handler (webpack-internal:///./pages/api/hello.js:4:9)
    at apiResolver (/home/jasonnet/jack_work/nextjs-blog/node_modules/next/dist/next-server/server/api-utils.js:8:7)
    at process._tickCallback (internal/process/next_tick.js:68:7)

which lists the error being at line 4 rather than 2.

This is just a trivial example. We have found that sometimes this APPEARS to work fine (ex. on linux with Next.js 11.0), but in actually the correct line number is shown by accident and simply adding an import at the top of the file reveals that it does not actually work. So I ask...

What is the supported way to fix this in 2021 vintage Next.js (ex. v10, v11) ?

Answer 1

If you are looking an answer for this in 2024 and using Next.js v14, then it is possible via two simple steps. Out-of-box, source-maps should work fine for development mode. But for production mode, you will need to make some adjustments. (Note that mapping back to source-maps is dependent on Node.js runtime support and thus the runtime mapping is not really specific to Next.js.)

First, you need to enable experimental flag for generating source-maps for server-side code:

// next.config.js
/** @type {import('next').NextConfig} */
const nextConfig = {
  experimental: {
    serverSourceMaps: true,
  },
};

export default nextConfig;

Second, when you run your production bundle code using next start, you need to tell Node.js via --enable-source-maps flag. Since, you cannot pass Node.js command line arguments directly with next CLI, you need to make use of NODE_OPTIONS environment variable to pass this flag:

NODE_OPTIONS='--enable-source-maps=true' next start

For, if you have a route handler with new app router:

import fs from 'node:fs/promises';

export const dynamic = 'force-dynamic';

export async function GET(request: Request) {

  const html = await fs.readFile('public/data.txt', 'utf8');

  throw new Error('This is an error message');  // Line no 9

  return new Response(html, {
    headers: {
      'content-type': 'text/plain; charset=utf-8',
    },
  });
}

This shall properly throw exception when this API route is accessed:

npm start

> [email protected] start
> NODE_OPTIONS='--enable-source-maps=true' next start

   ▲ Next.js 14.1.2
   - Local:        http://localhost:3000

 ✓ Ready in 188ms
 ⨯ Error: This is an error message
    at d (webpack://next-source-maps-example/src/app/api/route.ts:9:9)
    at <anonymous> (webpack://next/dist/esm/server/future/route-modules/app-route/module.js:189:37)
    at eI.execute (webpack://next/dist/esm/server/future/route-modules/app-route/module.js:128:26)
    at eI.handle (webpack://next/dist/esm/server/future/route-modules/app-route/module.js:251:30)
    at doRender (/Users/harshal/code/next-source-maps-example/node_modules/next/src/server/base-server.ts:2253:30)