Skip to content

Map stack traces through a loaded file's own source map with --enable-source-maps - #47713

Draft
robobun wants to merge 28 commits into
mainfrom
robobun/058ecf41/source-maps-switch
Draft

robobun wants to merge 28 commits into
mainfrom
robobun/058ecf41/source-maps-switch

Conversation

@robobun

@robobun robobun commented Nov 2, 2026 •

Copy link
Copy Markdown
Collaborator

Fixes #2125

Problem

  • Bun ignores the source map that a built file names with //# sourceMappingURL=. Error.stack says at boom (/repro/index.js:5:15). node --enable-source-maps says index.ts:6.
  • On main, --enable-source-maps and process.setSourceMapsEnabled() do nothing. module.setSourceMapsSupport() does not exist.

Fix

  • The three switches set one per-VM state on SavedSourceMap, off by default.
  • With it on, put_mappings keeps the URL of the comment. The first stack that needs the map reads it, as Node.js does since v26.9.0.
  • Each reader of a position names a space: Original for Error.stack and printed errors, Loaded for CallSite, coverage, snapshots and profiles.
  • Verified: test/js/bun/sourcemap/source-positions.test.ts, 36 new tests. Self-reviewed: 17 concerns raised, 15 addressed (see notes).

Background

Downsides

  • Switch off: +294 instructions per module load (+0.015%), +10 per stack frame, +24 KiB of binary. Each transpiler cache entry is written again once.
  • Switch on: the first stack that needs a map parses it (4.1 ms per MB), sometimes inside a collection. A printed error parses it again.
  • Not mapped yet: module.findSourceMap(), eval and new Function code, util.getCallSites(), index maps.
Notes

Repro (the files of the issue, tsc --sourceMap output):

$ bun index.js
error: kaboom
      at boom (/repro/index.js:5:15)
$ bun --enable-source-maps index.js
4 |
5 | function boom(): never {
6 |   throw new Error("kaboom");
                ^
error: kaboom
      at boom (/repro/index.ts:6:13)
      at main (/repro/index.ts:9:3)

The same with an inline data:application/json;base64, map. Node.js v26.13.0 prints index.ts:6:9 (V8 reports the column of new).

What the switch is. --enable-source-maps and process.setSourceMapsEnabled(v) set enabled, nodeModules and generatedCode to v. module.setSourceMapsSupport(enabled, { nodeModules, generatedCode }) sets each. process.sourceMapsEnabled and module.getSourceMapsSupport() read them. module.setSourceMapsSupport(), module.getSourceMapsSupport() and process.sourceMapsEnabled are new in Bun. A Worker takes the command-line value, or its own execArgv. bun test --isolate puts the command-line value back before each file. A module in node_modules is mapped only with nodeModules. A module is bound with the switch as it is when the module is asked for, and a lookup checks the switch again, as Node.js does.

How a position is mapped. The lexer records the URL of the last //# sourceMappingURL= or //@ sourceMappingURL= comment as V8 reads it (49 forms of the comment give the same answer as Node.js v26.13.0). The range goes through Ast, the printer and the transpiler cache to put_mappings, so a cache hit binds the same as a transpile. With the switch on, the table entry of the module is a record with Bun's map and the URL. An Original lookup first maps the running position to the loaded file, then reads the module's own map (once, a failure is kept) and maps on. Where the own map has nothing, the frame stays in the loaded file.

Node.js parity that the tests run. Where a Node.js of v26.9.0 or later is on PATH (CI has v26.12.1), these tests run the same fixture under Node.js and compare file and line: the 11 orderings of the switch, the node_modules rule, 54 forms of the URL, 21 forms of a source name, the ES module orderings, preloads, --target=node output and CallSite. test-module-setsourcemapssupport.js of Node.js v26.13.0 is added verbatim and passes. Every row was checked against v26.13.0 and v26.12.1. Node.js v26.8 and earlier read the map at module load, so three orderings differ there.

Measurements (release builds of cee9dd9 and of this branch, user instructions by perf_event_open with a fixed heap layout; perf, valgrind, strace and bloaty are not on the machine):

Module load, switch off (require of typeorm, 640 modules) +294 instructions per module, +0 reads, no .map opened
new Error().stack, switch off +29 instructions with 2 frames, +109 with 10
Cold start, switch off +1,568 instructions (+0.036%)
Transpiler cache +8 B per entry, 233 of 233 entries written again once, 0 when the switch changes
Ast 1,128 B to 1,136 B, the same allocation class. ResolvedSource stays 136 B
Binary +24,576 B, 2 host functions and 1 accessor
bun build --compile --aot --trim of hello world (CI, Linux x64) 25,961,444 B to 25,986,084 B mapped (+24,640 B). compile-aot-size.test.ts fails on main already: its limit is 25,880,000 B
Load with the switch on, nothing thrown no .map opened, +0 reads, +128 kB. Node.js v26.13.0 also opens none
First stack that needs a map 54,900 instructions per KB of map, 4.1 ms per MB, 20 B kept per mapping
A collection that is the first reader of 1,000 small maps +8.8 ms
console.error(error) with a 1 MB map that has sourcesContent 2.97 ms per print (0.13 ms with the switch off)
Record of a module 290 B with an external map, plus the length of an inline data: URL

bench/sourcemap/own-source-map-bench.mjs is a port of the benchmark of nodejs/node#65490 with two more phases. Load throughput with the switch off and on is within the noise of the base build in all five classes.

Differences from Node.js (all in docs/runtime/debugger.mdx):

  • Bun maps the position that JavaScriptCore reports in the loaded file. The column differs, and in minified code the line or the source file can differ.
  • A collection can be the first reader of a map. If a map changes while the program runs, the change can apply from another moment than in Node.js.
  • A module that an import() reaches through a static import gets the switch as it is when Bun loads that module.
  • When nothing has the text of the original source, Bun prints no source lines. Node.js prints the line of the loaded file.
  • A module that a require.extensions handler compiles with module._compile() is not mapped. A handler that changes the text before _compile takes the module's own map away.
  • A mapped frame keeps the function name of the loaded file. A frame on a line with no mapping stays in the loaded file.
  • --no-enable-source-maps is no flag, and Bun does not read NODE_OPTIONS.

Open, and why.

Suites run (debug build): source-positions.test.ts 361, external-sourcemap-stack-leak.test.ts 4, isolation.test.ts 157 (1 failure that main has too: a 5 s timeout in --isolate=modules), parallel.test.ts 57, transpiler-cache.test.ts 36, as-node.test.ts 13, node-module-module.test.js 85, sourcemap.test.js 14, require-extensions.test.ts 22, process.test.js 201 (1 failure that main has too: the host's Node.js version), worker_threads.test.ts 171, bundler_jsx.test.ts 66, inspect-error.test.js 47, capture-stack-trace.test.js 76, transpiler.test.js 258, bundler_comments.test.ts 50, six vendored Node.js tests. bun run rust:check-all passes for the 12 targets.


no test proof · iteration 9 · platform-specific test(s) that do not run on this machine, deferring to CI, which covers all platforms: test/js/node/process/process.test.js, test/js/node/module/node-module-module.test.js, test/js/bun/sourcemap/source-positions.test.ts, test/cli/test/parallel.test.ts, test/cli/test/isolation.test.ts, test/cli/run/transpiler-cache.test.ts, test/cli/run/as-node.test.ts

SavedSourceMap holds three flags: enabled, nodeModules and generatedCode.
The flags are the bits of one atomic byte. A thread that reads them sees
the state of one call.

--enable-source-maps is now a declared runtime flag. The flag turns the
three flags on when the VM starts. A Worker without an execArgv uses the
flag of its parent. A Worker with an execArgv uses only that list.
bun test --parallel sends the flag to its workers. bun test --isolate
puts the startup value back before each file. The package manager
commands ignore the flag, as they ignore the other runtime flags.

process.setSourceMapsEnabled() sets the switch. process.sourceMapsEnabled,
module.getSourceMapsSupport() and module.setSourceMapsSupport() are new.
Their values, defaults and errors are those of Node.js v26.3.0. The
Process object loses its unused m_sourceMapsEnabled field.

Nothing reads the switch yet, so stack traces do not change.
The lexer recorded the URL of a sourceMappingURL comment at a wrong
offset. The offset was the sum of the start of the comment and the
position of the pragma. The lexer now records the file offset of the
URL. The JSX pragmas had the same error, so a warning about one of them
pointed at a later line. The URL can now contain non-ASCII characters.

The parser copies the range of the URL to the Ast. The printer gives
the range to the source map handler and to the transpiler cache.
SavedSourceMap::put_mappings takes the range as a parameter. An entry
of the transpiler cache stores the range, so a cache hit gives
put_mappings the same value as a print. The cache version is now 44.

Nothing reads the range yet.
A file that another tool transpiled can name its source map in a
sourceMappingURL comment. Bun ignored that map. Error.stack and a
printed error showed positions in the file that was loaded.

The switch is --enable-source-maps, process.setSourceMapsEnabled(true)
or module.setSourceMapsSupport(true). With the switch off, nothing
changes and no map file is opened.

With the switch on, SavedSourceMap::put_mappings reads the map when the
module loads. It reads a data: URL and a path, as Node.js v26.3.0 does.
It does not read a URL with another scheme. It reads only a regular
file. A failure is silent. The table stores a new record. The record
has the map of the printer, the bytes of the module's map, and the file
that the sources are relative to. The nodeModules option applies at
load and at lookup. Nothing parses the bytes at load.

A reader of a stack position now states the file that it wants the
position in. PositionSpace::Original is for Error.stack,
Error.captureStackTrace, console.trace and a printed error. These
readers parse the bytes at the first lookup, outside the lock of the
table. Then they map the position a second time. PositionSpace::Loaded
is for CallSite objects, coverage, inline snapshots, test lines, the
test reporter, cron and CPU profiles. These readers get the position in
the loaded file, as before. Bun__remapStackFramePositions,
remap_stack_frame_positions, resolve_source_mapping and resolve_mapping
take the space as a required parameter.

parse_json and parse_url take a policy. ParsePolicy::Bun keeps the
rules for a map that Bun wrote. ParsePolicy::Node reads a map as
Node.js does. sourcesContent is optional. sourceRoot goes directly
before each source. A source resolves against the map file, or against
the module for a data: URL.

A printed error shows the lines of the original source if
sourcesContent or the original file has them. If not, it shows the line
of the loaded file and keeps the mapped frames, as Node.js does.

bun test --isolate keeps a transpiled module for the next file. A
change of the switch now clears that cache, because the map of a module
is read when the module is transpiled.
A FIFO in place of a source map file does not stop a module that
loads, with and without --enable-source-maps. The test runs on POSIX.

After --hot loads a changed file again, a new error is mapped through
the new source map of that file.
put_mappings keeps the URL of the sourceMappingURL comment and opens
nothing. The first reader that asks for an original position reads and
parses the map, and a map that cannot be used is not read again. Node.js
reads the map at the same time since v26.9.0.

The parse runs under its own AST allocator. A collection can format a
stack while a loader on the same thread walks an AST in the thread's
store, and parse_json resets that store.

put_mappings takes the switch as a parameter. The JS thread reads it when
it asks for the module, so a transpile on a pool thread does not depend
on when that thread runs.

bun test --isolate keeps a transpiled module by whether the switch asks
for the module's own source map. A change of the switch no longer empties
the cache of transpiled modules.

A printed error asks for the source text only when it shows a code frame,
and the record keeps the text that it took out of the map.

A path with a NUL from a sourceMappingURL comment or from the sources of
a map is not given to open.
…int, a NUL and two sources

The tests that say what Node.js does were run against node v26.13.0.
…able, as node and on reload

The tests load a module that has a sourceMappingURL comment while source maps are on.

- With --inspect, Error.stack is in the original file.
- An executable reads the source map of a file that it loads from disk. The frames of the bundled code stay where they are.
- --cpu-prof and a parse error give positions in the loaded file.
- With --isolate, a preload turns source maps on for each file. The second file takes the module from the cache.
- Without --isolate, the next file sees the process.setSourceMapsEnabled() call of the file before it.
- Bun as node reads the source map with --enable-source-maps.
- A module that loads again frees the record of the load before it.
The parse frame of a SyntaxError was mapped through the own source map of
the module, and the line of the error with it. The sourceURL of the error
stayed the loaded file, so the two did not name one place. Node.js
locates such an error in the loaded file.
…source text

A frame that a read of .stack or a collection put in the original file is
found again by the name of its source, in the own source maps that were
read. The lines of the loaded file are no longer shown under a frame in
the original file: only one order had them.

The record of a module keeps no source text. The parse that reads the map
for a printed error gives the text as well, and a later error reads the
map again, as for every other map.

One reader in bun_sourcemap opens every file that a source map names. It
refuses a NUL, a FIFO and a device.

With an Error.prepareStackTrace installed, the text that a collection
makes for an unread stack is in the loaded file, as the call sites are.

module.getSourceMapsSupport() gives one object until the switch is set
again, as in Node.js.
…its own source map

A transpiled module says whether it has a sourceMappingURL comment and
whether the switch asked for that map. bun test --isolate gives the module
to a later file only while the switch asks the same. A module with no
such comment is no longer transpiled again when the switch changes.
The scan of a Worker's execArgv for its flags goes through the option
table of the command line. The word after an option that takes a value
is the value of that option, and the scan goes on after it. The scan
stops at "--" and at the first positional. A word that the parser
rejects is skipped.

--enable-source-maps, --no-addons and --no-ffi-cc take effect after an
option and its value, for example after --require ./preload.js. A Worker
with --disallow-code-generation-from-strings there is refused. A word in
the place of a value is that value, also when it has the text of a flag.
The lexer records the URL only if the marker is the third byte of the
comment: //#, //@, /*# or /*@. This is the rule of esbuild. Before, a
mention of the comment in other text named a source map.

The runtime applies the rule of V8 to the recorded range. The comment
must be a // comment. Only white space can follow the URL on its line.
A comment that fails the rule gives the module no source map of its
own.

In debug builds, the lexer asserts that the range of each pragma
argument is where its text is in the source.

Three forms still differ from Node.js. docs/runtime/debugger.mdx lists
them.
The lexer records the URL of a comment that starts with //# or //@, one
white space character and sourceMappingURL=. White space before the URL
is not a part of it, and only white space ends it. A block comment names
no source map. The last such comment of a file counts, also when it has
no URL.

All 49 forms of the comment that were run give the same source map under
Node.js v26.13.0.

RuntimeTranspilerStore::transpile takes the switch from its caller.
A hook of Module.prototype._compile can give the native _compile another
text than the loader gave the hook. The own source map of the module is
for the file on the disk, so the module loses it then. A hook that gives
the text on as it is keeps the map.
…n, bun build and a minified bundle

The tests are in the block "a loaded file with its own source map".

An ES module gets the switch as it is when import() is called. A second
run takes the modules from the transpiler cache and prints the same.

A module that import() reaches through a static import gets the switch as
it is when Bun loads that module. Node.js gives it the switch as it is at
the import() call. The test has the value of Node.js beside each line.

A preload turns the switch on before the entry point loads its modules. A
module that the entry point imports turns it on too late for the next
import.

The text that the onLoad of a plugin returns is mapped when the path of
the module is a file path. It is not mapped in another namespace.

A file that bun build makes for Bun keeps the positions of its build,
with and without the switch. A file that bun build makes for Node.js is
mapped through its sourceMappingURL comment.

The collection that Bun runs after the entry point has loaded reads the
source map before the program reads a stack.

A frame of a one-line bundle of two sources can be in another source file
than the one Node.js reports. A printed error has no source lines when
nothing has the text of the source.

The documentation lists these differences from Node.js. It says which
built files keep the positions of their own build.
… --hot and --watch

The own source map of a module is read once for each load of the module.
A tool that builds a file writes the source map after it, so --hot could
load the module and read the map of the build before. The watcher now has
the file of the map, and a change of it loads the module again.
…etSourceMapsSupport

Eight tests in the block "a loaded file with its own source map" say what
Node.js prints. Each of them now runs its program under the Node.js on the
PATH too, when that Node.js is v26.9.0 or later. Node.js gets a folder of
its own with the same files. The test compares what Node.js prints with
the table that Bun is held to, by the file and the line of each frame.
Without such a Node.js, the test runs Bun only.

The table of sourceMappingURL forms has four new rows: a path with a drive
letter, with slashes and with backslashes, a backslash in a relative path,
and a host. The table of source names has two new rows: a backslash in a
relative source, and a source that starts with two slashes. These rows run
on every platform.

test-module-setsourcemapssupport.js is the file of Node.js v26.13.0.
Node.js refuses such a URL there. On Windows it is a UNC path. The rows
of the tests that Node.js answers the same run under Node.js too, where a
Node.js that reads source maps lazily is on the machine.
The bench is a port of benchmark/module/module-require-source-map.js of
Node.js. It loads modules with no source map, with an inline source map
and with an external source map. It also loads modules of more than
4 KiB, and modules through import().

Each class of module runs with the source maps switch off and with it
on, in a process of its own. A run has three phases: the load, the first
read of a stack of each module, and in Bun a collection that is the
first reader of the source maps. The file runs under Node.js too, with
--enable-source-maps.
@robobun

robobun commented Nov 2, 2026 •

Copy link
Copy Markdown
Collaborator Author
Updated 4:19 PM PT - Nov 4th, 2026

❌ @robobun, your commit 1c1ceb5 has 39 failures in Build #137640 (All Failures):


🧪   To try this PR locally:

bunx bun-pr 47713

That installs a local version of the PR into your bun-47713 executable, so you can run:

bun-47713 --bun

@robobun

robobun commented Nov 2, 2026 •

Copy link
Copy Markdown
Collaborator Author

Status

…rol character out of a Windows file name

The AOT test that reads every getter of the host objects prints the new
process.sourceMapsEnabled getter.

Windows has no file with a control character in its name, so the row of
the URL table that needs one runs on POSIX only.
@robobun

robobun commented Nov 2, 2026

Copy link
Copy Markdown
Collaborator Author

The two failures in test/aot/engine/ir-1.test.ts and test/aot/engine/ir-5.test.ts do not come from the code of this PR. They come from a defect in the AOT engine that main pins (oven-sh/WebKit 4d45755fed). oven-sh/WebKit#971 fixes that defect. #47605 moves WEBKIT_VERSION to an engine that has the fix.

Why this PR shows it

  • The two tests are valueflow/modules/plugin-named-on-an-object-filled-under-the-keys-of-the-bun-module-with-flow-rules-delayed.ir and the ...-of-an-import-of-the-bun-module-... file beside it. They run the flow solver with testing=DelayFlowRules.
  • That switch holds back about half of the due rules in each round. A hash selects them, and the hash includes the ids of built-ins.
  • This PR adds three names to the table of built-ins (getSourceMapsSupport, setSourceMapsSupport, sourceMapsEnabled). The ids move, so the two tests get a different order of the rules.
  • In that order the pinned engine does not see that copy.plugin can be Bun.plugin. It prints unseen-code no.

The defect is on main without this PR

  • On main (3f3a9ff), the same program with # OPTIONS: testing=DelayFlowRules:108 fails in the same way.
  • With the table of main, 1 of 256 schedules fails. With the table of this PR, 3 of 256 fail (the default, 126 and 250).

Cause in the engine

Verified

Next step

After #47605 merges, merge main into this branch. The two tests pass then. This PR needs no change for them.

…ce-maps-switch

# Conflicts:
#	src/sourcemap/Mapping.rs
…ce-maps-switch

# Conflicts:
#	src/jsc/RuntimeTranspilerStore.rs
#	src/jsc/SavedSourceMap.rs
#	src/jsc/VirtualMachine.rs
#	src/runtime/hw_exports.rs

This branch has not been deployed

No deployments
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Support existing source maps in stack traces

2 participants