Skip to content
Tutorials Center
My learning

Topics

Node.js Reference ยท CLI Flags

Node.js --stack-trace-limit and --enable-source-maps

Reference for node --stack-trace-limit and --enable-source-maps: see more stack frames, map errors back to TypeScript or bundled sources, and the cost.

Two flags make error stack traces more useful. --stack-trace-limit=<n> sets how many frames V8 records for each error (the default is 10), which helps when the real cause is deep in a call chain. --enable-source-maps makes Node translate positions in generated JavaScript back to the original files, so a crash in compiled or bundled code points at your TypeScript or source lines.

Both only change what is printed or stored in error.stack; neither changes how your program behaves.

NODE
// shell: node --stack-trace-limit=50 --enable-source-maps dist/app.js

Try it

Node.js Seeing more frames

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with node:readline or process.stdin), it gets the next line from this box.

Node.js Source maps in a stack trace

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with node:readline or process.stdin), it gets the next line from this box.

Syntax

NODE
// shell
node --stack-trace-limit=<n> <script>
node --enable-source-maps <script>
NODE
// in code
Error.stackTraceLimit = 50;   // affects errors created afterwards
Name Description
--stack-trace-limit=<n> Maximum number of frames recorded per error. 0 records none.
--enable-source-maps Applies source maps (external .map files or inline data: URLs) to stack traces.

Returns: nothing. The effect shows in error.stack, uncaught-error output and console.trace().

Edge cases: the frame limit counts frames at the moment an error is created; changing Error.stackTraceLimit later does not alter older errors. Source maps are read lazily, only when a stack is formatted.

Usage notes

  • Deep recursion and async code: the default of 10 often cuts off the interesting part. Try 50 or 100 while debugging, but remember that capturing a stack costs time and memory for every error object.
  • Error.stackTraceLimit = Infinity records everything; avoid it in production because creating errors in hot paths becomes expensive.
  • Source maps and performance: with --enable-source-maps, building a stack can be noticeably slower, and large maps use memory. Many teams enable it in development and for crash reports, not for every request-heavy server.
  • Where the map comes from: a //# sourceMappingURL= comment pointing to a file next to the generated code, or an inline data: URL (as in the example). TypeScript's sourceMap option and bundlers generate these.
  • Error cause and async traces: V8 adds async frames for awaited calls; the limit applies to them too.
  • Native .ts files: when Node strips types itself, positions are preserved by blanking out the types rather than moving code, so traces already point at the right line and no map is needed (--experimental-strip-types).
  • NODE_OPTIONS accepts both flags, which is handy for tools that start Node for you.