Source Map Generation & Stack Trace Debugging

Q: Which devtool or sourcemap setting should I use in production?

Use hidden-source-map for Webpack and sourcemap: 'hidden' for Vite. Both emit a complete, high-fidelity map but omit the // sourceMappingURL comment so browsers never fetch it. Upload the map out-of-band to your error tracker and delete it from the deploy artifact. Reach for nosources-source-map when you cannot risk original code reaching even a trusted third party.

Q: How do I symbolicate a stack trace I already have, outside of my error tracker?

Run Mozilla's source-map library in a small Node script: load the matching .map, construct a SourceMapConsumer, and call originalPositionFor({ line, column }) for each minified frame. This is exactly how the on-demand resolution and Node CLI workflows linked above operate, and it is the right tool for one-off forensic debugging of a logged trace.

Production JavaScript ships minified, mangled, and bundled, so the stack trace your error tracker receives points at a.b.c (main.4f2a.js:1:88421) instead of the function and line a human wrote. Closing that gap is a pipeline, not a single setting: the build step must emit an accurate source map, that map must be stored where attackers cannot read it but your error tracker can, and at incident time the minified frames must be re-expanded — symbolicated — back into original file, line, and column. This page is the architectural index for that pipeline. It connects the build-tool configuration covered in Configuring Webpack for Production Source Maps, the engine-specific parsing in Cross-Browser Stack Trace Normalization Techniques, and the release-time automation in CI/CD Source Map Upload and Validation. The goal is a deterministic chain where every byte of minified output has a verifiable path back to source, with no original code leaking to the public and no version drift breaking the mapping.

Core Runtime Patterns & Interception Layer

A source map is only useful once an error has been captured with its raw stack intact, so the interception layer sits upstream of everything on this page. The runtime mechanics of catching uncaught exceptions, normalizing rejection reasons, and attaching V8 async frames belong to the Core JavaScript Error Handling & Boundaries pillar; here the concern is narrower — preserving a high-fidelity stack string so the downstream symbolicator has something to resolve. The single most common way teams lose resolvability is by re-wrapping errors and discarding the original error.stack before it leaves the browser.

Capture the raw stack as early as possible and forward it verbatim. Do not trim frames, do not re-throw with new Error(message) (which resets the stack to the wrapper’s location), and do not stringify in a way that collapses column numbers — column data is what distinguishes two minified statements packed onto the same line.

window.addEventListener('error', (event) => {
  // Forward error.stack verbatim; the column number is load-bearing for minified code.
  if (event.error && event.error.stack) {
    telemetry.capture({
      message: event.error.message,
      stack: event.error.stack,        // raw, un-trimmed frames
      release: __BUILD_ID__            // ties this stack to a specific map set
    });
  }
});

The release field is the join key between a runtime error and the build that produced it. Without it, the error tracker has no deterministic way to pick the correct .map, and a deploy that happened five minutes before the error fired will silently symbolicate against stale mappings.

There is a second fidelity trap unique to minified code: the engine populates error.stack lazily, and some capture paths read it after a transform has already mutated the error. The safest moment to read the stack is inside the handler that first observes the error, before any of your own middleware touches it. If you maintain a custom logger that wraps errors for context, attach the context as a separate property rather than constructing a new Error, so the original stack survives intact all the way to the wire.

// Preserve the original stack; attach context as a sibling field, never re-throw.
function enrich(err, context) {
  err.context = context;          // does NOT touch err.stack
  return err;                     // returning new Error(...) here would destroy resolvability
}

Asynchronous code complicates this because each await boundary can reset the synchronous portion of the stack. V8 stitches async frames back together when --async-stack-traces is active (the default in modern Node and Chromium), but the stitched frames still reference minified positions and still need a map. The interception layer’s only obligation is to forward whatever the engine produced; the work of merging engine-specific async-frame formats is deferred to the normalization layer described later. Treat the captured stack as opaque text at this stage — parsing it in the browser wastes CPU on the hot path and risks dropping frames the server-side normalizer would have kept.

One more browser-specific hazard belongs here. Errors thrown by scripts loaded cross-origin without crossorigin="anonymous" arrive as the opaque string "Script error." with no stack at all, so there is nothing for any map to resolve. This is a CORS issue, not a source-map issue, but it is the reason a perfectly configured map pipeline can still show unresolvable errors; the fix — setting crossorigin and matching CORS headers — is covered under the core error-handling pillar’s interception guidance.

Framework-Specific Isolation

Each bundler emits source maps differently, and the H2-level decision — which devtool or sourcemap option, where the map URL points, whether original sources are embedded — is made per framework. Webpack exposes a devtool matrix where the difference between source-map, hidden-source-map, and nosources-source-map controls both fidelity and exposure; the full decision tree is in the Webpack production source-maps guide, and the per-option trade-offs are walked through in choosing the right webpack devtool setting. Vite uses esbuild and Rollup under the hood with a simpler build.sourcemap: 'hidden' flag, covered in Vite Build Settings for Accurate Stack Traces.

// webpack.config.js — generate maps as separate files with no sourceMappingURL comment
module.exports = {
  mode: 'production',
  devtool: 'hidden-source-map',   // emits .map but omits the //# comment from the bundle
  output: {
    filename: '[name].[contenthash].js',
    chunkFilename: '[name].[contenthash].chunk.js'
  }
};

hidden-source-map is the safe production default for Webpack: it produces a complete, high-fidelity map but strips the //# sourceMappingURL= comment so browsers never auto-fetch it. The map is then uploaded out-of-band to the error tracker. The word hidden refers only to that comment — the file itself is just as readable as any other if it is reachable by URL, which is why generation settings and storage controls are two separate links in the chain rather than one. A team that sets hidden-source-map but forgets to delete the .map from dist/ before deploy has secured nothing; the file is still a public download away. For Vite, the equivalent is the hidden value rather than true, detailed in how to generate hidden source maps in vite.

// vite.config.js — hidden maps emit files without the trailing sourceMappingURL comment
export default {
  build: {
    sourcemap: 'hidden',          // 'true' would leak the map URL to the browser
    rollupOptions: { output: { entryFileNames: 'assets/[name].[hash].js' } }
  }
};

The choice within a bundler is not binary. Webpack’s devtool is a matrix crossing four independent axes — whether the map is a separate file or inlined, whether original source is included, whether column information is retained, and whether the result is built with eval wrappers. Faster development presets like eval-cheap-module-source-map trade column accuracy for rebuild speed, which is acceptable while you are at the console but disastrous in production where a missing column collapses distinct minified statements onto one source position. The production end of the matrix is deliberately narrow: source-map, hidden-source-map, and nosources-source-map, differing only in exposure. Picking the wrong development preset and forgetting to override it for production builds is one of the most common ways teams accidentally ship inline source to a CDN.

Vite’s model is simpler but has its own sharp edge around code-splitting. Because Rollup generates a separate chunk (and a separate map) for every dynamic import, the base path each chunk’s map uses must resolve correctly relative to where the chunk is actually served. When assets are rehosted on a CDN with a different path prefix than the build assumed, the sources entries point at directories that no longer exist, and the tracker shows the right line in a file it labels with a broken path. Resolving that requires aligning the build’s public base with the deploy’s real URL, which is why CDN path rewriting and dynamic-import chunking are recurring themes across the build cluster.

The deeper failure mode in the framework layer is transpilation chaining. Babel rewrites your source before the bundler sees it, and if intermediate maps are not composed, every frame shifts by the offset Babel introduced. That composition bug is the subject of why source maps break after babel transpilation, and the related path-rewriting problem after CDN deploys is handled in fixing incorrect source map paths after cdn deployment. Vite users hit a parallel issue when dynamic imports produce chunks whose maps reference the wrong base; see fixing vite source maps with dynamic imports.

Source Map Architecture & Stack Trace Resolution

A source map is a JSON document conforming to the Source Map v3 specification. The fields that matter are version (always 3), sources (the original file paths), names (original identifier names for de-mangling), mappings (the encoded position table), and the optional sourcesContent (inlined original code). The entire mapping table is a single string of Base64 VLQ-encoded segments grouped by output line; each segment carries deltas for output column, source index, source line, source column, and name index. Understanding this layout is what lets you debug a map that looks present but resolves to the wrong place — the full structure is documented in Understanding Source Map v3 Specification and Formats, with the encoding itself walked through byte by byte in decoding vlq mappings by hand.

{
  "version": 3,
  "sources": ["src/checkout.ts"],
  "names": ["validateCart", "total"],
  "mappings": "AAAA,SAASA,aAAaC,...",
  "sourcesContent": ["export function validateCart(total) { ... }"]
}

The mappings string is where most confusion lives, so it is worth being precise about its grammar. Output lines are separated by ;; within a line, segments are separated by ,. Each segment is one to five VLQ-encoded numbers, and every number is a delta from the previous segment’s corresponding field, not an absolute value. The first field (generated column) resets to zero at the start of each output line, but the source index, source line, source column, and name index carry their running totals across the entire file. This relative encoding is what keeps maps compact, and it is also why a single corrupted segment cascades: every subsequent position in the file is now offset by the broken delta, so the symptom is “everything after line 200 resolves one statement too early.” A segment with only one field means “this output position has no corresponding source” — typically injected runtime or wrapper code — and a robust consumer must treat those as gaps rather than guessing.

Resolution — turning main.4f2a.js:1:88421 into src/checkout.ts:42:8 — is a binary search over the decoded mapping table for the segment whose generated position is nearest at or before the reported column. There is a performance dimension to where this runs. Parsing a large map and building its lookup structure costs real CPU and memory, so symbolicating a high-volume error stream by re-parsing the same map per event is wasteful. The standard remedies are to parse each map once and keep the SourceMapConsumer warm in a cache keyed by release and file, and to resolve frames in batch. At very high volume, teams precompute and store resolved signatures so repeat occurrences of a known error skip resolution entirely. These optimizations are the difference between a symbolication service that keeps up with an incident spike and one that backs up its queue exactly when you need it most.

Most teams never implement this by hand; they let the error tracker do it on upload, or run Mozilla’s source-map library server-side. The library-driven approach is the subject of Local Symbolication with Mozilla source-map Library, including symbolicating stack traces in a node cli script for ad-hoc debugging and caching parsed source maps for faster symbolication when you symbolicate at volume.

import { SourceMapConsumer } from 'source-map';

// Resolve one minified frame back to its original position.
const consumer = await new SourceMapConsumer(rawMapJson);
const original = consumer.originalPositionFor({ line: 1, column: 88421 });
// → { source: 'src/checkout.ts', line: 42, column: 8, name: 'validateCart' }
consumer.destroy();

For large applications, two structural concerns shape the architecture. The first is index maps (also called sectioned maps), a v3 feature where a top-level map contains a sections array, each entry pairing an offset with either an inline map or a URL to one. Index maps let a concatenated bundle reference per-module maps without re-encoding the whole table, which matters when many independently built modules are stitched together — a federated or micro-frontend setup. A consumer that does not understand the sections field will silently fail to resolve frames in the later sections of such a bundle. The second concern is sourcesContent: embedding original code makes a map self-contained and resolvable offline, but it doubles as a source-code leak if the map is ever exposed. The privacy section below treats that as a security decision rather than a format one.

When no map is available — a third-party script, a hotfix that skipped upload, a vendor chunk — you fall back to reading the minified bundle directly. Techniques for that, including pretty-printing in DevTools and recovering identifier intent, live in Debugging Minified Code Without Source Maps and mapping minified variable names back to source.

Resolution accuracy also depends on what the minifier did to function names. Mangling rewrites validateCart to a, and the only record of the original identifier lives in the map’s names array, referenced by the fifth field of a segment. If your minifier was configured to drop names — some aggressive presets do — the map can still resolve to the correct file and line but will report the function as anonymous, which weakens grouping because two distinct functions on adjacent lines look identical to the tracker. Keeping names is cheap and worth it; the array deduplicates strings and compresses well. When you control the toolchain, verify that the terser or esbuild settings used in production retain name information in the emitted map even while mangling the bundle itself.

The other half of resolution is normalizing the input stack before lookup, because no two engines format frames identically. V8 (Chrome, Node, Edge) prefixes each frame with at and parenthesizes the location; SpiderMonkey (Firefox) uses an @ separator; JavaScriptCore (Safari/WebKit) uses yet another shape and omits some frames entirely. A parser that assumes one format silently drops frames from the others, skewing error grouping. Anonymous functions, arrow callbacks, and code generated through eval or new Function are the hardest cases: V8 labels them <anonymous>, Firefox may give a synthetic eval frame, and the column offsets inside an eval string are relative to the eval source, not the outer file, so naive resolution lands on the wrong position entirely. The normalizer’s job is to canonicalize all of these into a single frame shape — function name, absolute source URL, line, column — before any map lookup runs, so the symbolicator sees one consistent input regardless of which browser reported the error. The normalization layer’s engine-specific handling is detailed in normalizing v8 and spidermonkey stack frames and the awkward handling anonymous and eval frames in stack traces. Compatibility across the full browser matrix — including Safari’s quirks and Firefox async frames — is consolidated in Cross-Browser Source Map and Stack Compatibility, parsing safari webkit stack trace format, and capturing firefox async stack traces.

Observability SDK Setup & Privacy Controls

The privacy stakes of source maps are unusual: a complete map with sourcesContent is your source code. Anyone who can fetch main.4f2a.js.map from your CDN can reconstruct your entire frontend. The first control is generation — hidden-source-map and nosources-source-map both remove the sourceMappingURL comment, and nosources additionally strips sourcesContent so even a leaked map reveals only positions, not code. The second control is storage. Maps should never sit on a public CDN path; they belong in private storage that only the error tracker reaches.

The hardening playbook — auth-gated map endpoints, IP allowlists, and ephemeral tokens — is the subject of Securing Hidden Source Maps from Public Access, with two concrete deployments: serving source maps behind authentication and restricting source map access by ip allowlist.

# Block every public request for .map files while allowing internal upload tooling.
location ~ \.map$ {
  allow 10.0.0.0/8;     # private network / build runners only
  deny all;             # browsers and the public internet get 403
}

There is a meaningful distinction between the two hidden modes that drives the decision. hidden-source-map keeps sourcesContent, so a leaked map fully reconstructs your source — its protection is entirely operational (the file must stay private). nosources-source-map removes sourcesContent, so a leaked map reveals only that “minified column X corresponds to original file Y at line Z” without the line’s text. For an open-source frontend the distinction is moot, but for proprietary code it is the difference between an embarrassing leak and a non-event. The trade-off is that nosources resolution requires the tracker to also have a copy of the original sources to display the offending lines, which it gets at upload time over a private channel rather than from the map itself.

Beyond storage, the SDK boundary is where you strip PII from the payloads the map will be attached to. Error grouping should key off the symbolicated signature (original file plus function plus line) rather than the raw minified frame, so that a single bug does not fragment into one issue per release hash. Configure the SDK to attach the release identifier on every event, redact query strings and tokens from frame URLs, and set a sampling rate appropriate to volume — the same privacy and sampling controls used by browser SDKs in the core error-handling pillar apply here unchanged.

Grouping deserves emphasis because it is downstream of symbolication quality and easy to get wrong. If the tracker groups by raw minified frame, then every release — with its new content hash and new mangled names — produces a brand-new fingerprint for the same underlying bug, and a single recurring crash fragments into dozens of issues that nobody can correlate. Grouping by the symbolicated signature collapses them, but only if symbolication is deterministic and the function name survived mangling. This is the practical payoff of retaining the names array and matching release hashes precisely: it is not merely about reading one trace, it is about the tracker’s ability to count one bug as one bug across every deploy it appears in. Treat a sudden bloom of low-volume issues after a deploy as a symptom of broken symbolication, not of new bugs.

CI/CD Integration & Release Correlation

Everything above fails the moment the uploaded map and the deployed bundle disagree. The job of CI/CD is to make that disagreement impossible: build once, derive a deterministic release identifier, upload the maps under that identifier, and fail the pipeline if any map is missing. The cardinal rule is “build once, deploy many” — never rebuild between staging and production, because a rebuild can produce different hashes and orphan the maps you already uploaded. Promote the exact artifact, maps and all, through environments.

A robust pipeline has four ordered stages. First, build with a hidden source-map setting and a release identifier injected from the commit. Second, validate that every emitted .js has a sibling .map, failing fast if the transpiler skipped a chunk. Third, upload the maps to the tracker under the release, then strip them from the deploy artifact so they never reach the CDN. Fourth, after deploy, run a synthetic-error probe in staging and assert that the tracker resolved it to the expected source line. Only after the fourth stage passes is the release considered verified end to end. Each stage is independently failable, which means a broken map never silently ships; the pipeline goes red instead. A worked GitHub Actions integration of these stages is in uploading source maps from github actions to sentry.

#!/usr/bin/env bash
set -euo pipefail
RELEASE=$(git rev-parse --short HEAD)   # deterministic, matches __BUILD_ID__ in the bundle

# Upload all maps under the release, then delete them from the deploy artifact.
sentry-cli sourcemaps upload --release "$RELEASE" ./dist/assets/
find ./dist -name '*.map' -delete       # maps must not ship to the CDN

Two guardrails turn this from best-effort into enforced. The first is a build gate that counts emitted .js files against emitted .map files and exits non-zero on mismatch, so a transpiler that silently skipped a chunk cannot reach production — see failing the build when source maps are missing. The second is a post-deploy smoke test that throws a known error in staging and asserts the error tracker resolves it to the expected source line, proving the whole chain end to end; that technique is injecting synthetic errors in staging to verify symbolication.

Determinism in the build step is a precondition for any of this to hold. If two builds of the same commit produce different content hashes — because a dependency resolved to a different patch version, or because the bundler embedded a timestamp — then the map you uploaded for build A will not match the bundle a CDN cache is still serving from build B, and resolution silently degrades. Lock dependencies, disable timestamp injection, and derive the content hash from bundle bytes so the same source always yields the same artifact. The CI pipeline should treat the map set as a build output of equal importance to the bundle: produced in the same job, fingerprinted with the same hash inputs, and uploaded before the bundle is allowed to reach production.

Ordering matters too. Upload maps before flipping traffic to the new release, not after. If the bundle goes live first, every error in the window between deploy and upload arrives with no resolvable map and is recorded with raw minified frames — which then poison error grouping permanently, because the tracker has already created an issue keyed on the unresolved signature. Gating the traffic switch on a successful upload step closes that window.

The release identifier is the thread that ties build, storage, upload, and runtime capture together. Use the same value in __BUILD_ID__ baked into the bundle, in the --release flag at upload, and in the release field on every captured event. When they match, symbolication is deterministic; when they drift — a re-run that produced a new content hash, a cache that served an old bundle — the tracker resolves against the wrong map and reports plausible-looking but wrong source lines, which is more dangerous than no symbolication at all.

Common Mistakes

Issue	Impact
Shipping `eval-source-map` or `inline-source-map` to production	Embeds full original source inside the bundle, exposing all code to anyone who opens DevTools and inflating download size.
Using `devtool: 'source-map'` (with the `//# sourceMappingURL` comment) on public assets	Browsers auto-fetch the `.map` from the CDN, leaking source to the public even though the bundle is minified.
Deployed bundle hash differs from the uploaded map’s release	Tracker resolves frames against a stale map and reports wrong file/line, producing confidently incorrect debugging leads.
Re-throwing as `new Error(msg)` before capture	Resets `error.stack` to the wrapper location, so symbolication points at the logging utility, not the real fault site.
Parsing only V8-format stacks	Firefox (`@`) and Safari/WebKit frames are dropped, skewing error grouping and hiding browser-specific failures.
Leaving `.map` files in the deployed `dist/` directory	A public, fetchable map defeats `hidden-source-map`; the comment’s absence does not matter if the file is reachable by URL.
Stripping column numbers when forwarding stacks	Multiple minified statements share one line; without the column the lookup cannot distinguish them and resolves to the wrong statement.
Uploading maps with `sourcesContent` to a third-party tracker for closed-source apps	Hands your complete original source to an external vendor; use `nosources` plus position-only resolution if that is unacceptable.

FAQ

Which devtool or sourcemap setting should I use in production? Use hidden-source-map for Webpack and sourcemap: 'hidden' for Vite. Both emit a complete, high-fidelity map but omit the //# sourceMappingURL comment so browsers never fetch it. Upload the map out-of-band to your error tracker and delete it from the deploy artifact. Reach for nosources-source-map when you cannot risk original code reaching even a trusted third party.

Why does my error tracker show wrong line numbers even though the map uploaded successfully? This is almost always a release-hash mismatch or an uncomposed Babel map. Confirm the release on the captured event equals the --release used at upload and equals the bundle’s build identifier. If they match, check that your Babel-to-bundler map chain is being composed rather than overwritten, since an intermediate transform shifts every frame by a fixed offset.

Do source maps slow down or affect end users? No, when generated as separate hidden files. The browser only downloads a .map if it encounters a sourceMappingURL comment and DevTools is open, and hidden/nosources settings remove that comment. Maps never execute and add no runtime cost; they exist purely for the error tracker and developers to resolve frames after the fact.

How do I symbolicate a stack trace I already have, outside of my error tracker? Run Mozilla’s source-map library in a small Node script: load the matching .map, construct a SourceMapConsumer, and call originalPositionFor({ line, column }) for each minified frame. This is exactly how the on-demand resolution and Node CLI workflows linked above operate, and it is the right tool for one-off forensic debugging of a logged trace.

How do I keep maps available for debugging without exposing source code? Generate hidden maps, store them in private storage gated by authentication or an IP allowlist, and grant access only to your error tracker’s upload tooling. For closed-source apps, additionally strip sourcesContent so a leaked map yields only positions, never code, and rely on position-only resolution that maps to file names and line numbers without revealing the lines themselves.