skip to content

In Chrome DevTools, a production stack frame still reads `checkout.4be1.js:1:90412` in the Console and Sources; how do you work out why no source map applied?

level: seniorimportance: must knowfreq 45%

answer

  1. start on the deployed file itself
  2. the notice names the failure
  3. failed, skipped or loaded
  4. no reference means attach by hand
  5. wrong lines mean a different build

basics

~20 s

Open the deployed file in Sources and read its notice: failed to load, skipped, or loaded. No notice points to the setting or a missing reference, where Add source map attaches one by URL. Wrong lines mean another build's map.

solid answer

~50 s

I open the deployed file in Sources, because DevTools reports the map's state there. `Source map failed to load` comes with the URL and the error, so it is a path or access problem, and Developer resources shows its status. `Source map skipped for this file` tells you to make sure the file isn't on the ignore list and reload. No notice usually means the **JavaScript source maps** setting is off or the file carries no map reference. If I hold the map privately, I right-click in the editor and use `Add source map…` with its URL. `Source map loaded` with nonsense positions means the map came from a different build, so I need that build's map. I check each frame's own file too, since one chunk can be mapped while another is not. With no map at all, I fall back to the pretty-printed deployed code.

go deeper

for a junior

Recall that a location like line 1, column 90412 is a position in the shipped file, and that Sources shows a notice on that file saying whether its source map loaded.

for a middle

Explain the three notices, failed, skipped and loaded, and what each one sends you to check. Know that Add source map can attach a map the shipped file does not reference.

for a senior

Work from evidence in order: which file, which setting, which notice, which error. Treat a loaded map as unproven until a frame matches the deployed code, and keep moving on pretty-printed code if no map exists.

for a principal

The tradeoff is how fast an engineer can reach the map for a given deployed build during an incident versus who may reach it at all. Decide that access in advance, since DevTools can only use a map someone can fetch.

## The symptom and where to look first A frame such as `checkout.4be1.js:1:90412` is a location in a **deployed** file: line 1, column 90412 of a minified bundle. A **source map** would translate it to an original file and line, so seeing the raw location means no map is applied to that file. Do not start by rebuilding anything. Start by opening that deployed file in the Sources panel, because Chrome DevTools attaches a notice to the top of the editor describing what happened to its map. That notice separates the causes faster than guessing. ## Read the notice | What the editor shows | What it means | What to do | |---|---|---| | `Source map failed to load` | A reference exists, and the request failed | Read `Error loading URL ...`, then fix the path or the access | | `Source map skipped for this file` | A reference exists, and no load was recorded | Make sure the file isn't on the ignore list, then reload | | `Source map loaded` | A map is applied | If positions look wrong, suspect a different build | | No notice | Setting off, no reference, or notice turned off | Check the setting, then attach a map by hand | The wording of the skipped notice is worth remembering: `To enable again, make sure the file isn't on the ignore list and reload`. It catches people who ignore-listed a whole bundle to quiet the debugger and then wonder why it stays minified. Absence of a notice is weaker evidence than it looks. DevTools shows nothing when the **JavaScript source maps** setting is off and nothing when the file has no map reference, and the loaded and skipped notices can also be turned off. Only the failure notice has no such setting. ## A systematic pass Work through it in this order: 1. **Check every frame's file.** A stack can cross several chunks. One may be mapped while its neighbour is not, so diagnose the file that is actually unmapped. 2. **Check the setting.** Find **JavaScript source maps** in the Sources section of DevTools Settings. If it is off, no script is mapped, and the `Add source map…` item is not offered either. 3. **Read the deployed file's notice.** Follow the table above. 4. **Open the Developer resources panel on a failure.** It lists map requests with their status and any error, and you can filter it by URL or error text. 5. **Attach the map by hand if the file has no reference.** Right-click in the editor on the deployed file, choose `Add source map…`, and give the map's URL. 6. **Verify the result.** The original file should appear in the file tree, and a frame should now open a line that makes sense for that frame. ## Why a map can fail when the file looks fine A few causes account for most failures: - **The map is not reachable from your machine.** A map on an internal host or behind a login is simply unreachable without your network or session. - **The request is treated differently from a page load.** By default DevTools requests the map itself rather than the page doing so, and that request may be treated as cross-origin. Developer resources has an option to load through the page instead. - **The URL is a remote file path.** The setting `Allow loading remote file path resources in DevTools` is disabled by default for security reasons, and source maps are the example its own tooltip gives. - **The file is on your ignore list by pattern.** `Add source map…` is not offered for a URL you ignore-listed, and the skipped notice can appear for it. ## When a map loads and is still wrong `Source map loaded` proves only that a file was fetched. It does not prove the map belongs to this bundle. A map from another build has a plausible file list and wrong positions, so breakpoints land on odd statements and frames name the wrong functions. The check is direct: click through to the deployed code at a frame and compare what is there with the original line DevTools claims it came from. If they disagree, you need the map from the exact build that is deployed. A bundle whose file name contains a content hash makes that matching easier to reason about. ## When there is no map at all You can still debug. DevTools pretty-prints a deployed file automatically, so you can read the code and pause in it. Names stay shortened, so navigate by what minification usually leaves intact, such as string literals and property names. Search for an error message from the UI or a route path, and you usually land near the logic you want. That is slower, but it does not depend on anyone finding a file for you.

  • What does it mean if the deployed file shows no source map notice at all?
    Less than it seems. DevTools shows nothing when the JavaScript source maps setting is off and nothing when the file has no map reference. The loaded and skipped notices can also be turned off, so check the setting before concluding the file has no map, then try Add source map if you hold one.
  • Why might a map that opens in a browser tab still fail to load in DevTools?
    By default DevTools requests the map itself, not the page, and that request may be treated as cross-origin. Opening a URL in a tab is a different kind of request. Read the error in the Developer resources panel, try its option to load through the page, or point Add source map at a copy you can reach.
  • You have no map and cannot get one. How do you still make progress on the bug?
    Debug the deployed code. DevTools pretty-prints it, and although names stay shortened, string literals and property names usually survive minification. Search the file for an error message or route path, pause near it, and read the logic. It is slower, but it needs nothing from the build.

  • No source map notice proves the production file has no map.
  • Source map loaded means the positions DevTools shows are correct for this bundle.
  • A skipped source map always means a server error on the map's URL.
  • Without a map reference in the shipped file, DevTools has no way to use a map.
  • If the map URL opens in a browser tab, DevTools must be able to load it too.
  • Without a source map, a minified production bundle cannot be debugged at all.