JS Error Hub

Debugging Source Maps in Browser DevTools

When a production error resolves to app.9f2c1.js:1:44820 in your monitoring dashboard, the fastest way to turn that coordinate into a readable line of your original code is often the browser itself — provided its DevTools can find and trust the source map. This guide covers the interactive side of source map debugging: enabling and troubleshooting map resolution in Chrome and Firefox, wiring the deployed bundle to your on-disk source with Workspaces, patching a live production file with Local Overrides, and clearing the “Source map not found” and “Could not load content” warnings that quietly disable symbolication. It is part of the wider Source Map Generation & Stack Trace Debugging reference. If your maps are missing entirely rather than merely unresolved, start with Debugging Minified Code Without Source Maps; if the warnings trace back to how the bundle emits its sourceMappingURL, Configuring Webpack for Production Source Maps covers the emit side.

After working through this guide you will be able to:

  • Enable and confirm source map resolution in both Chrome and Firefox DevTools.
  • Map a deployed bundle to your local checkout with a DevTools Workspace so edits round-trip to disk.
  • Serve a modified copy of a production file to a live tab using Local Overrides, without redeploying.
  • Diagnose and fix the four warnings that silently turn off symbolication in the Sources panel.
  • Jump from a monitored production stack frame to the exact original line interactively.

Problem Framing & Symptom Identification

The symptom is deceptively small: you open the Sources panel, click a stack frame, and land on a single unreadable line of minified output instead of your original component. Sometimes there is a yellow warning banner at the bottom of the editor pane — “Source map detected but could not be loaded” — and sometimes there is nothing at all, just minified code where you expected .tsx. The absence of any error is the harder case, because it usually means DevTools never even looked for a map.

There are four distinct failure signatures, and telling them apart before you touch anything saves the most time:

  1. No map requested. The bundle carries no //# sourceMappingURL= comment and no SourceMap HTTP header, so DevTools has nothing to fetch. The Sources tree shows only the minified file, with no lighter-grey “original” entries beneath it.
  2. Map requested, fetch failed. The comment or header points at a URL that returns 404, 403, or the wrong content type. DevTools surfaces this under the Console’s Issues tab or as a faint warning in the Sources footer.
  3. Map loaded, sourcesContent empty. The map resolves positions but was generated with nosources-source-map, so DevTools can show file names and line numbers but cannot display the code — you get a greyed placeholder reading “Could not load content for …”.
  4. Map loaded, positions wrong. Everything resolves, but the highlighted line is off by several lines or points at the wrong file — a sign of a stale map whose build hash no longer matches the deployed bundle.

DevTools exposes the raw state directly. In Chrome, right-click any file in the Sources tree and the context menu shows “Source map” entries only when a map is attached. The most reliable probe, though, is the Console:

// Paste into the DevTools Console on the failing page.
// Lists every script the page loaded and whether it advertises a map.
performance.getEntriesByType('resource')
  .filter((e) => e.name.endsWith('.js'))
  .forEach((e) => console.log(e.name));
// Then fetch the tail of the suspect bundle to see its sourceMappingURL comment:
fetch('https://cdn.example.com/assets/app.9f2c1.js')
  .then((r) => r.text())
  .then((t) => console.log(t.slice(-160)));
// Look for: //# sourceMappingURL=app.9f2c1.js.map  (present = category 2/3/4, absent = category 1)

If the tail shows a sourceMappingURL comment, the map is at least advertised and you are debugging a fetch, content, or staleness problem. If it shows nothing, the comment was never written or was stripped after build — which is a bundler concern, not a DevTools one.

One subtlety catches people repeatedly: a map can also be advertised through an HTTP response header, SourceMap: app.9f2c1.js.map, rather than an in-bundle comment. Servers that strip trailing comments to shave a few bytes sometimes add the header instead, and the tail-of-file check above will show nothing even though DevTools resolves the map perfectly. When the comment is absent but symbolication still works, inspect the script’s response headers in the Network panel before concluding the map is missing. Conversely, a header that points at a stale path will 404 exactly like a bad comment, so both channels are worth checking when the symptom is category two.

DevTools source map statesA vertical flow of four DevTools source map states: no map requested, fetch failed, content empty, and positions wrong, ending at resolved mapping.No map requestedFetch failed 404 or 403Content empty or staleResolved mapping

Prerequisites & Environment Setup

You need a recent evergreen browser and a local checkout of the code that produced the deployed bundle. Workspaces and Local Overrides both depend on DevTools features that have shifted names across versions, so pin to something current:

# Confirm browser versions (Chrome 116+ and Firefox 129+ recommended).
google-chrome --version    # e.g. Google Chrome 126.0.6478.126
firefox --version          # e.g. Mozilla Firefox 129.0

# A local source checkout that matches the deployed release.
git clone https://github.com/example/app.git
cd app
git checkout "$(curl -s https://cdn.example.com/assets/build-meta.json | node -pe 'JSON.parse(require("fs").readFileSync(0)).commit')"

# Node and the bundler used to (re)generate maps locally when needed.
node --version             # v18.19.0 or later
npm ci                     # restore the exact dependency tree from the lockfile

Enabling the features themselves is a one-time toggle per browser. In Chrome, open DevTools, press the gear icon for Settings, and under Preferences → Sources confirm both “Enable JavaScript source maps” and “Enable CSS source maps” are checked — they ship on by default but are the first thing a corporate policy or a teammate disables. In Firefox, the equivalent lives under the Debugger panel’s settings gear as “Enable Source Maps”. Neither browser will show a warning when the setting is off; maps simply never resolve, which is exactly the silent category-one symptom from the previous section.

For Local Overrides you also need a scratch folder that DevTools may write to. Create one outside your repository so overridden files never get committed by accident:

# A writable folder DevTools will use to persist overridden responses.
mkdir -p ~/devtools-overrides

Step-by-Step Implementation

1. Attach and Verify the Map in the Sources Panel

Load the failing page with DevTools open, switch to the Sources panel, and expand the tree for the origin serving your bundle. When a map resolves, DevTools inserts the original files as lighter-coloured entries — often grouped under a synthetic webpack:// or ../src/ root — directly beneath the minified script. Click one; you should see your original, un-minified code. If you only see the minified file, force a re-fetch of the map from the Console so you can read the exact failure reason instead of guessing:

// Manually fetch the advertised map and inspect the response status + shape.
const mapUrl = 'https://cdn.example.com/assets/app.9f2c1.js.map';
const res = await fetch(mapUrl);
console.log('status', res.status);                 // 200 = reachable; 404/403 = category 2
const map = await res.json();
console.log('version', map.version);               // must be 3 for the current spec
console.log('sources', map.sources.length);        // list of original files
console.log('hasContent', Array.isArray(map.sourcesContent) && map.sourcesContent.some(Boolean));
// hasContent === false means nosources-source-map: names resolve, code will not display.

A 200 with hasContent: true but no original files in the tree points at DevTools caching a previous failed attempt — right-click the bundle and choose “Clear source map”, then reload.

2. Bind the Bundle to Local Source with a Workspace

A Workspace (historically “Workspaces”, now surfaced as the Sources → Workspace tab, and earlier as “Filesystem”) lets DevTools treat a folder on disk as the authoritative source for files it recognises from the map. Once bound, editing a file in the Sources panel writes straight through to disk, and breakpoints you set survive reloads because DevTools maps the deployed URL to your local path by content.

// After adding the folder in DevTools (Sources > Workspace > "Add folder"),
// confirm the mapping resolved by checking a source file's persistence icon.
// In the Console you can verify the map's source paths line up with your tree:
const map = await (await fetch('https://cdn.example.com/assets/app.9f2c1.js.map')).json();
console.log(map.sourceRoot || '(none)');           // prefix DevTools prepends to each source
map.sources.slice(0, 5).forEach((s) => console.log(s));
// e.g. "webpack://app/./src/components/Cart.tsx" must correspond to src/components/Cart.tsx

In the UI: open Sources → Workspace, click Add folder, and select your repository root. Grant the permission prompt. DevTools compares the map’s sources paths against the folder and marks matched files with a green dot. A matched file now shows your edits persisted to disk — a purple/green dot in the tab — instead of the ephemeral in-memory edit you get without a Workspace.

The matching is by path suffix, not by absolute location, which is what makes it resilient to the webpack:// and sourceRoot prefixes bundlers prepend. DevTools takes each map source such as webpack://app/./src/components/Cart.tsx, strips the synthetic prefix, and looks for src/components/Cart.tsx beneath the folder you added. If your repository nests the app under a subdirectory — a common monorepo layout like packages/web/src/... — add that subdirectory rather than the monorepo root so the suffix lines up. When nothing matches, the fastest diagnosis is to print the map’s sources array (from step one) beside your find src -name '*.tsx' output and compare the tails; the mismatch is almost always an extra or missing path segment.

3. Serve a Patched File with Local Overrides

Local Overrides is the counterpart to Workspaces: instead of mapping the deployed file to your source, it lets you intercept the network response for any URL and serve a locally stored, edited version — including the map itself. This is the mechanism for testing a one-line production fix against the real, live backend before you cut a release.

// Enable Overrides via Sources > Overrides > "Select folder for overrides",
// point it at ~/devtools-overrides, and accept the permission banner.
// You can even override the .map file to correct a bad sourceMappingURL locally:
// 1. Right-click app.9f2c1.js in the Sources tree > "Save for overrides".
// 2. Edit the last line to point at a map you control, then reload.
console.log('%cOverrides active', 'color:#16a34a');  // sanity marker in the Console
// DevTools now serves your edited copy for that exact URL on every reload,
// bypassing the CDN entirely for that one file until you clear the override.

Overridden files display a purple dot in the Sources tree and, in newer Chrome, a small overrides badge in the Network panel’s “Override” column. Because the override intercepts before the CDN, you can fix a broken sourceMappingURL, add a missing map comment, or patch the actual buggy line — all against production traffic — then verify the behaviour end to end.

Local Overrides request flowA horizontal pipeline showing a page request intercepted by the DevTools overrides folder and served the edited file, bypassing the CDN.Page requests JSOverrides folderEdited file served

4. Resolve “Source Map Not Found” Warnings

The warning most people hit is a 404 on the .map file, which happens constantly after a CDN move because the bundle’s relative sourceMappingURL no longer resolves against the new origin. DevTools reads the comment as a URL relative to the script’s own location, so //# sourceMappingURL=app.9f2c1.js.map resolves to whatever directory served the script. When maps live in a separate, access-controlled path, that relative resolution misses.

# Reproduce the browser's resolution locally to prove the URL is wrong.
# The map URL DevTools computes = script directory + the comment value.
SCRIPT="https://cdn.example.com/assets/app.9f2c1.js"
COMMENT="$(curl -s "$SCRIPT" | grep -o 'sourceMappingURL=[^ ]*' | cut -d= -f2)"
echo "comment: $COMMENT"
# Resolve it the way the browser does and probe the status.
MAP_URL="$(dirname "$SCRIPT")/$COMMENT"
curl -s -o /dev/null -w '%{http_code}\n' "$MAP_URL"   # 404 confirms the not-found warning

You have three fixes, in order of preference. First, serve the map from the path the comment expects (adjust your bundler’s sourceMapFilename/publicPath). Second, if the map is intentionally private, drop the in-bundle comment entirely and rely on server-side symbolication — see Securing Hidden Source Maps from Public Access. Third, for a purely local debugging session, use the Local Overrides technique from the previous step to rewrite the comment to a URL you control, or use Chrome’s per-file “Add source map…” context-menu action to paste a working map URL by hand.

5. Map a Production Stack Frame to Its Original Line

With a resolving map attached, turn a monitored coordinate into a source location interactively. Take the raw file:line:column from your error tracker and drive DevTools to it. The reliable path is the Console Ctrl+G/Cmd+G “Go to line:column” jump inside the opened source, but you can also confirm the mapping programmatically against the fetched map so you trust what DevTools shows:

// Sanity-check a specific minified coordinate resolves to the expected original.
// Uses the source-map library you can load in a scratch Node script.
import { SourceMapConsumer } from 'source-map';
import { readFileSync } from 'node:fs';

const raw = JSON.parse(readFileSync('./app.9f2c1.js.map', 'utf8'));
await SourceMapConsumer.with(raw, null, (consumer) => {
  // The coordinate from the error tracker: app.9f2c1.js:1:44820
  const pos = consumer.originalPositionFor({ line: 1, column: 44820 });
  console.log(pos);
  // Expect: { source: 'webpack://app/./src/components/Cart.tsx', line: 88, column: 12, name: 'checkout' }
  // A null source means DevTools will land on minified code — the map is stale or wrong.
});

If this resolves cleanly but DevTools still shows the minified line, the browser is holding a cached map from an earlier load. Clear it via right-click “Clear source map” on the bundle and hard-reload, or disable the DevTools cache under Network → Disable cache while DevTools is open.

Production Telemetry Integration

Interactive DevTools debugging and automated production symbolication should agree on the exact same map, keyed by the exact same release identifier. When they disagree, DevTools shows you one original line and your error tracker shows a different one — usually because the tracker uploaded a map for a release the deployed bundle no longer matches. The fix is to make the release identifier visible at runtime so you can confirm, from the live tab, which build you are actually debugging.

// src/monitoring.js — expose the release on window so DevTools can read it live.
import * as Sentry from '@sentry/browser';

const RELEASE = __RELEASE__; // injected at build time (git SHA or semver+build)
window.__APP_RELEASE__ = RELEASE;

Sentry.init({
  dsn: process.env.SENTRY_DSN,
  release: RELEASE,           // ties every event to the map uploaded for this build
});

Now, from the DevTools Console on any production tab, window.__APP_RELEASE__ tells you precisely which build’s map you should be inspecting. Cross-check it against what the tracker holds so you never debug against a stale map:

# Confirm the tracker has a map uploaded for the release the live tab reports.
# Run the release value you read from window.__APP_RELEASE__ through the CLI.
RELEASE="8c1f4ab"
npx @sentry/cli sourcemaps explain "$EVENT_ID"      # shows whether the map matched
npx @sentry/cli releases files "$RELEASE" list      # lists uploaded artifacts for that release
# If the list is empty, the deployed bundle has no matching map on the server —
# DevTools may still resolve locally via a Workspace, but the tracker cannot symbolicate.

There is a second, quieter reason to expose the release at runtime. When an incident spans several deployed versions — a rolling deploy, a canary, or a sticky-session A/B split — different users hit different bundles, and therefore different maps. A developer reproducing the bug in their own browser may be served a newer build than the one that generated the tracked event, so the DevTools view and the tracker view legitimately disagree even though nothing is broken. Reading window.__APP_RELEASE__ in the reproducing tab and comparing it against the event’s release field settles that ambiguity in seconds, instead of sending you hunting for a mapping bug that does not exist.

For teams running a full pipeline, keeping the interactive and automated paths in sync is a CI concern; CI/CD Source Map Upload and Validation covers gating a deploy on a successful upload so the map a developer opens in DevTools is guaranteed to exist on the tracker too.

Verification & Testing

Prove the map resolves before you invest time reading code. The quickest confirmation is visual — original files appear in the Sources tree and clicking a stack frame lands on readable code — but automate the check so it holds across builds. This scripted probe validates the three properties DevTools depends on: reachability, spec version, and content availability.

# End-to-end map health check against a deployed bundle.
BUNDLE="https://cdn.example.com/assets/app.9f2c1.js"
MAP="${BUNDLE}.map"

# 1. The map must be reachable (not the 404 that produces the not-found warning).
test "$(curl -s -o /dev/null -w '%{http_code}' "$MAP")" = "200" \
  && echo "OK: map reachable" || echo "FAIL: map 404/403"

# 2. It must be a v3 map with content, or DevTools shows "could not load content".
curl -s "$MAP" | node -e '
  const m = JSON.parse(require("fs").readFileSync(0));
  if (m.version !== 3) { console.log("FAIL: not source map v3"); process.exit(1); }
  const hasContent = Array.isArray(m.sourcesContent) && m.sourcesContent.some(Boolean);
  console.log(hasContent ? "OK: sourcesContent present" : "WARN: nosources map (names only)");
'

Then verify the interactive path itself. Set a breakpoint through the mapped original file, trigger the code path, and confirm execution pauses on your source line rather than the minified line — this proves the column mapping, not just the file mapping, is correct:

// Paste in the Console to force a known error whose frame you can click through.
// If DevTools opens the original .tsx at the right line, column mapping is sound.
try {
  JSON.parse('{ broken');            // throws a SyntaxError with a mapped frame
} catch (err) {
  console.error(err);                // click the frame link: should open original source
  console.assert(window.__APP_RELEASE__, 'release marker missing — wrong build loaded');
}

If the frame link opens the original file at the correct line, the full chain — comment, fetch, content, and position mapping — is verified. If it opens minified code, walk back up: category one (no comment), two (fetch), three (content), or four (stale), using the Problem Framing signatures.

Before and after map resolutionA before and after comparison contrasting minified single-line debugging against resolved original source with breakpoints and readable names.NO MAPOne minified lineSingle-letter namesColumn guessworkMAP RESOLVEDOriginal TSX shownReal symbol namesBreakpoints on source

Failure Modes & Edge Cases

Scenario Root Cause Fix
Original files never appear in Sources tree “Enable JavaScript source maps” toggled off in DevTools settings Re-enable under Settings → Preferences → Sources, then reload
“Source map not found” after CDN move Relative sourceMappingURL resolves against the new origin and 404s Serve the map at the expected path, drop the comment for private maps, or override the URL locally
“Could not load content for …” placeholder Map built with nosources-source-map; sourcesContent is empty Rebuild with hidden-source-map, or use a Workspace to supply the code from disk
Breakpoint binds to wrong line Deployed bundle hash drifted from the uploaded/loaded map Clear the source map, disable cache, reload against the matching release
Workspace folder shows no green dots Map sources paths do not correspond to the added folder’s layout Add the folder at the level the sources prefix expects, or adjust sourceRoot
Override never takes effect Overrides folder permission revoked, or Network cache serving CDN copy Re-grant the folder, enable Network → Disable cache, confirm the purple override dot

FAQ

Why do original files show in the Sources tree but clicking a frame still lands on minified code?

The map resolved for the file but not for that specific position, which almost always means the loaded map is stale relative to the deployed bundle. Right-click the bundle and choose “Clear source map”, enable Network → Disable cache, then hard-reload so DevTools re-fetches both the script and its map together. Confirm with window.__APP_RELEASE__ that the tab is running the build whose map you expect.

What is the difference between a Workspace and Local Overrides?

A Workspace maps a deployed file to your local source so edits in DevTools persist to disk and breakpoints survive reloads — it is for developing against your own checkout. Local Overrides intercepts the network response and serves a locally stored, edited copy for any URL, including third-party scripts and the .map file itself — it is for patching or correcting a response you do not build. Use a Workspace when you own the source; use Overrides when you need to change what the browser receives for a specific URL.

How do I fix a “source map not found” warning without redeploying?

Use Chrome’s per-file “Add source map…” context-menu action in the Sources panel to paste a map URL you control, or enable Local Overrides and edit the bundle’s //# sourceMappingURL= comment to point at a reachable map. Both are session-local and never touch the deployed artifact, which makes them safe for debugging a live incident before the real fix ships.

Can I use these DevTools techniques identically in Firefox?

Mostly. Firefox’s Debugger has the same source map toggle and resolves maps the same way, and it exposes original sources in the Sources tree. Its Workspace-equivalent and override tooling differ in naming and coverage — for JavaScript, Firefox leans on the Debugger’s own mapping rather than a filesystem override folder. Engine-level differences in stack frame and column numbering are covered in Cross-Browser Stack Trace Normalization Techniques.