Learning center

Map a minified stack trace to source with the exact build's source map

A source map turns app.min.js:1:84 into a source line, but only the map from the same build. Another build's map returns a confident answer that points at the wrong code.

Reproduced: one position, two maps#

A small checkout module was bundled and minified with esbuild 0.25.0, with source maps. The source has a bug on line 3 of cart.js: it reads cart.coupon.percent when a cart has no coupon.

export function formatTotal(cart) {
  const subtotal = cart.items.reduce((sum, item) => sum + item.price * item.quantity, 0);
  const discount = cart.coupon.percent / 100;
  return (subtotal * (1 - discount)).toFixed(2);
}

Running the minified bundle threw:

TypeError: Cannot read properties of undefined (reading 'percent')
    at e (app.min.js:1:84)
    at c (app.min.js:1:153)

Mapping line 1, column 83 (the trace's column 84 minus one) with the build's own map, using the source-map library's originalPositionFor, returned cart.js, line 3, column 31 counted from 0: cart.coupon.percent. That is the bug. source-map library ยท Source map format, ECMA-426

Then one line was added at the top of formatTotal and the bundle rebuilt. Mapping the same stack position with the new build's map returned cart.js, line 3, column 58 counted from 0, name item: the reduce callback, which has nothing to do with the error. Both answers look equally plausible in a ticket.

Two causes of a misleading mapped trace#

Cause A: the map belongs to another buildCause B: the map is right and the trace is incomplete
SignThe mapped line cannot throw the reported error, such as an addition mapped from reading 'percent'The mapped line can throw it, but the reason is in a caller
CheckCompare the script's file name or content hash in the trace with the build whose map you usedMap every frame, not only the top one
FixGet the map from the same build, keyed by releaseRead the callers' frames and the data they passed

The deciding observation is whether the mapped line can produce the error message. A reading 'percent' error must map to an expression that reads .percent. If it does not, stop and find the right map.

Get the right map#

Source maps are matched to scripts by a comment at the end of the generated file, //# sourceMappingURL=app.min.js.map, or by a SourceMap response header. ECMA-426: linking generated code to source maps

  • Hashed file names make the match exact: app.3f9c1a.min.js names one build. A trace with an unhashed name such as app.min.js needs the release identifier recorded with the error.
  • Error trackers usually key uploaded maps by a release string. Check that the release on the error event matches a release that has maps uploaded.
  • DevTools loads the map automatically when the script and map are available, and shows original files in the Sources panel. If the map is not public, DevTools can load one from a URL you give it. DevTools: source maps
  • Node.js applies maps to its own stack traces with --enable-source-maps. With it, the reproduction printed at formatTotal (src/cart.js:3:32). Node.js: source maps

Column numbers differ by convention: stack traces count from 1, and the source-map library's originalPositionFor expects columns from 0. Subtract one before you look up a column.

Worked example: a mapped trace that pointed at the wrong function#

This example is fictional and follows the reproduction above. A user's error report included TypeError: Cannot read properties of undefined (reading 'percent') at e (app.min.js:1:84). An engineer mapped it with the map from the current release and got the reduce callback in formatTotal, line 3. They spent an hour looking for an item without a price.

The error event's release field said checkout@2026.11.18, two days before the current release. With that release's map, the same position mapped to cart.coupon.percent, which can throw exactly this message for a cart with no coupon.

A better report would have opened with: reading 'percent' at app.min.js:1:84 in release checkout@2026.11.18, mapped with that release's map to cart.js:3:32, cart.coupon.percent. Naming the release and the map is what makes the mapped line trustworthy.

What to put in the report#

  • The raw stack trace, unmapped, exactly as recorded.
  • The script URLs in it, with their hashes, and the release or build identifier.
  • The mapped frames, and which map you used for them.
  • Whether the mapped top frame can produce the error message.

Questions#

Should source maps be public?

That is a product decision. Public maps make debugging in any browser easy and expose your source. Many teams upload maps only to their error tracker or serve them to authenticated staff. A report should say where the map came from, not change the policy.

Why does the mapped trace show the right file but the wrong line?

The map belongs to a different build of the same file, or a later build step, such as a second minifier, changed the code after the map was generated. Check that the map was produced by the last step that wrote the script.

What if the error has no stack at all?

If the message is Script error. with no file, the script is cross-origin and muted. See Script error with no details.

Return to the method for browser bug reports for the other symptoms in this collection.

One month of free code review.

New organizations get one calendar month of hosted code review for private and public GitHub repositories. No card or cloud connection required. Eligibility and fair-use terms.

Start free with GitHub

Related reading