skip to content

In Node.js 24, why do stack traces from compiled TypeScript point at the `.js` output, and what does `--enable-source-maps` change?

level: middleimportance: should knowfreq 30%

answer

  1. V8 reports the code it ran
  2. a sourceMappingURL comment is ignored by default
  3. opt in with a flag or API
  4. Error.stack gets slower

basics

~20 s

V8 reports positions in the JavaScript it actually ran, and Node ignores sourceMappingURL comments by default. --enable-source-maps makes Node load those maps and rewrite stack frames to original .ts lines, at a cost each time Error.stack is read.

solid answer

~40 s

A compiled service runs `dist/*.js`, so V8's stack frames name those files and lines. The compiler can append a `//# sourceMappingURL=` comment, but Node.js only parses source maps when support is switched on: with `--enable-source-maps`, with `NODE_V8_COVERAGE` set, or with `module.setSourceMapsSupport(true)`. Once on, Node caches the maps and rewrites frames to the original `.ts` file and line on a best-effort basis. The documented cost is latency whenever `Error.stack` is accessed, and a custom `Error.prepareStackTrace` must call the original one or the mapping is lost. `setSourceMapsSupport()` skips `node_modules` by default and only affects modules loaded afterwards; the CLI flag covers both. Built-in type stripping needs no map at all, because types are replaced by whitespace and every position survives.

code

bash · 1 line
bash
node --enable-source-maps dist/server.js

go deeper

for a junior

Recall that compiled TypeScript runs as JavaScript, so stack traces show dist files unless Node is started with --enable-source-maps.

for a middle

Explain how the sourceMappingURL comment, the flag and the map cache combine, and why type stripping keeps positions without any map.

for a senior

Diagnose unmapped stacks: missing map files in the artifact, a custom Error.prepareStackTrace, or a programmatic switch called too late.

for a principal

Weigh mapped stack traces against the latency they add to Error.stack, and pick a team default for how error locations are recovered.

## Why the frames point at JavaScript A **stack trace** lists the functions that were executing when an error was created, with a file, line and column for each. V8, the engine inside Node.js, produces those positions from the code it actually compiled. When a TypeScript service is built ahead of time, Node runs `dist/server.js`, not `src/server.ts`, so every frame names the compiled file. The compiler may have reordered, down-levelled or wrapped code, so a line in `dist` can be far from the line you wrote. A **source map** is the bridge: a JSON document (in the ECMA-426 format, formerly "Source Map revision 3") that maps positions in generated code back to positions in the original sources. Compilers point to it with a trailing comment such as `//# sourceMappingURL=server.js.map`, or embed it inline as a `data:` URL. ## Node does not read maps by default Node only parses those comments when source map support is **enabled**. There are three ways: 1. **`--enable-source-maps`** on the command line. This is the usual production choice. It has been non-experimental since v15.11.0. 2. **`NODE_V8_COVERAGE=dir`**, which turns on map handling as part of collecting coverage. 3. **`module.setSourceMapsSupport(true, options)`** from code, available since v22.14.0 and v23.7.0. With support on, Node fills a cache of maps as modules load, and when a stack trace is formatted it makes a best-effort translation of each frame back to the original file and line. ## The programmatic switch is narrower than the flag | | `--enable-source-maps` | `module.setSourceMapsSupport(true)` | |---|---|---| | Files under `node_modules` | included | skipped unless `nodeModules: true` | | Code from `eval` or `new Function` | included | skipped unless `generatedCode: true` | | Modules loaded before it takes effect | all, set at startup | only modules loaded after the call | The documentation recommends the command-line flag precisely so that maps for early-loaded modules are not missed. `module.getSourceMapsSupport()` reports the current `enabled`, `nodeModules` and `generatedCode` values, and `module.findSourceMap(path)` lets tooling read a cached map. ## What it costs - **Latency on `Error.stack`.** The documentation warns that enabling maps can add latency when `Error.stack` is accessed, so services that read `error.stack` in hot paths (logging every handled error, for example) pay for it each time. The Node documentation calls this out directly. - **Interaction with `Error.prepareStackTrace`.** A library that overrides it may stop the mapping. The fix is for the override to call and return the original `Error.prepareStackTrace`. ## When no map is needed Node's built-in **type stripping** replaces type syntax with spaces instead of deleting it, so every remaining token keeps its original line and column. A `.ts` file run directly gets correct stack positions with no map, and Node does not generate one. The exception is `--experimental-transform-types`, which rewrites code such as `enum` and therefore **implies `--enable-source-maps`**. A runner that rewrites code at load time needs a map for the same reason a build does. ## A worked diagnosis An on-call engineer sees `at handler (/app/dist/routes/orders.js:212:17)` in an error log and cannot find line 212 in any source file. The steps that resolve it: 1. Confirm how the process was started: `process.execArgv` or the start command shows whether `--enable-source-maps` is present. 2. Confirm the artifact: the last line of `orders.js` should be a `sourceMappingURL` comment, and the referenced `.map` file must exist next to it in the deployed image. 3. Confirm nothing overrides `Error.prepareStackTrace` without delegating to the original. 4. Restart with the flag and reproduce; the frame should now name `src/routes/orders.ts` and the original line. If the service had been running its `.ts` files through built-in type stripping instead, step 1 would already have answered the question: the frame would name the `.ts` file at the right line. ## Practical guidance - Ship maps with compiled output and start the service with `--enable-source-maps` so error reports and logs reference `.ts` lines. - Measure if the service formats stacks at a high rate; mapped stacks cost more to produce. - Prefer the flag over the programmatic switch unless you need to scope maps away from `node_modules`. - If stacks stay unmapped, check for a custom `Error.prepareStackTrace` and confirm the `sourceMappingURL` comment and map file are actually deployed. Knowing which of these four cases a service is in (stripped, transformed, built, or mapped by a runner) is what turns "the stack trace is wrong" into a one-line fix.

  • A team enabled `--enable-source-maps`, yet frames still show dist paths. What do you check first?
    First, whether a library overrides `Error.prepareStackTrace` without calling the original, which the Node documentation says can prevent mapping. Next, whether the deployed `.js` files still carry their `sourceMappingURL` comment and the referenced `.map` files exist at that path in the image. Maps that were stripped from the artifact cannot be applied.
  • Why does running `node server.ts` with built-in type stripping not need `--enable-source-maps`?
    Because stripping overwrites type syntax with whitespace instead of removing it, so every JavaScript token stays on its original line and column. The positions V8 reports already match the `.ts` file. Node generates no map in this mode; only `--experimental-transform-types`, which rewrites code, implies source maps.

  • Node applies sourceMappingURL comments automatically without any flag.
  • Type stripping needs --enable-source-maps for correct line numbers.
  • --enable-source-maps has no runtime cost at all.
  • setSourceMapsSupport(true) also maps modules loaded before the call.
  • Source maps change which code V8 actually executes.

Assumes Node.js 24, where type stripping needs no source maps; --enable-source-maps is stable since v15.11.0 and module.setSourceMapsSupport() exists since v22.14.0.