JS Error Hub

Why Source Maps Break After Babel Transpilation

When you add babel-loader to a Webpack pipeline and set a devtool like hidden-source-map, stack traces can still resolve to minified bundle positions rather than original source lines—because babel-loader silently drops intermediate map data by default, severing the chain that configuring Webpack for production source maps depends on, a deeper symptom within the broader challenge of source map generation and stack trace debugging.

Babel source map loader chain: broken vs fixed Two parallel horizontal pipelines. The top pipeline (broken) shows a .js source file passing through babel-loader with sourceMaps:false, producing a red severed chain before Webpack merge, resulting in a broken .map file. The bottom pipeline (fixed) shows the same source file passing through babel-loader with sourceMaps:true and inputSourceMap:true, preserving the green chain through Webpack merge to a valid .map file. BROKEN FIXED src/app.js (original source) babel-loader sourceMaps: false ✗ ✗ Webpack merge (no map to merge) bundle.js.map → transpiled positions only src/app.js (original source) babel-loader sourceMaps: true ✓ Webpack merge (composes maps ✓) bundle.js.map → original src lines ✓ Map chain severed (sourceMaps:false) Map chain intact (sourceMaps:true + inputSourceMap:true)

Symptom / Trigger

The tell-tale sign is that your APM tool or browser DevTools reports a stack frame pointing deep into the bundled output with a suspiciously high column number:

TypeError: Cannot read properties of undefined (reading 'filter')
  at app.bundle.js:1:47821
  at n (app.bundle.js:1:320)
  at Object. (app.bundle.js:1:1044)

Chrome DevTools may show the source panel loading the transpiled output—complete with Babel-generated _asyncToGenerator helper wrappers—rather than your original ES modules. Sentry and Datadog will report the error location as webpack://app.bundle.js or webpack:///webpack/bootstrap. Running source-map-explorer on the bundle produces the message Unable to map all bytes.

If you open the .map file directly and inspect the mappings field, valid entries map bundle columns back only to post-babel transpiled line numbers, not to original source lines. That is the footprint of a severed intermediate map.

Root Cause Explanation

Webpack invokes loaders in right-to-left order. Each loader receives two arguments: the source string and an optional source map object from the previous loader. The loader is expected to transform the source and pass both the new source and an updated source map along the chain. Webpack’s internal source-map library then composes all intermediate maps into a single final .map file.

babel-loader has two independent options that control this behavior:

  • sourceMaps — whether Babel itself generates a map for the code it emits.
  • inputSourceMap — whether Babel accepts and threads through a map it receives from an earlier loader in the chain.

Both default to false. The result is that when Webpack hands babel-loader the source alongside any prior map (say, from ts-loader), babel-loader ignores that map and emits transpiled code with no map of its own. Webpack’s merge step therefore has nothing to compose:

// webpack.config.js — BROKEN: babel-loader silently discards all map data
module.exports = {
  devtool: 'hidden-source-map',
  module: {
    rules: [{
      test: /\.js$/,
      use: {
        loader: 'babel-loader',
        // No sourceMaps or inputSourceMap options — both default to false
        options: {
          presets: ['@babel/preset-env'],
        }
      }
    }]
  }
};

Even with devtool: 'hidden-source-map' set, the final .map file maps bundle positions back to the transpiled output that Babel produced, not to the original source. If Babel also collapses output to a single line (its default compact: true behavior for minified-looking input), every position resolves to line 1 of the transpiled intermediate, making stack traces completely useless.

There is an additional subtlety: the sourceMaps option in babel.config.js and the sourceMaps option inside babel-loader’s options block are independent. Setting it in babel.config.js tells Babel to generate a map when invoked programmatically or via the CLI, but babel-loader overrides this with its own option. Both locations must be configured correctly, or one will silently win.

Step-by-Step Fix

Step 1: Enable sourceMaps in babel.config.js

Set this as a baseline so every invocation of Babel—CLI, Jest, and the loader—generates maps by default:

// babel.config.js
module.exports = {
  presets: [
    ['@babel/preset-env', { modules: false }]
  ],
  sourceMaps: true,  // Emit maps for all Babel invocations
};

Setting modules: false is also important: it prevents @babel/preset-env from converting ES module import/export to CommonJS, which would cause Webpack’s own tree-shaking and code-splitting logic to rewrite the module graph in ways that invalidate positional data.

Step 2: Pass sourceMaps: true and inputSourceMap: true to babel-loader

The loader-level option overrides babel.config.js, so it must be set explicitly. inputSourceMap: true tells Babel to accept and incorporate any source map it receives from a prior loader:

// webpack.config.js (loader rule)
{
  test: /\.js$/,
  exclude: /node_modules/,
  use: {
    loader: 'babel-loader',
    options: {
      sourceMaps: true,        // Babel emits a map for its output
      inputSourceMap: true,    // Babel threads through maps from prior loaders
    }
  }
}

Step 3: Disable compact mode to preserve line structure

Babel’s compact: true (the default when output exceeds 500 KB) collapses all output onto a single line. This turns every mapping into a line-1 reference, which is indistinguishable from a broken map. Disable it explicitly:

// webpack.config.js (loader rule, continued)
{
  loader: 'babel-loader',
  options: {
    sourceMaps: true,
    inputSourceMap: true,
    compact: false,   // Preserve line structure so column mappings are meaningful
  }
}

Note that compact: false increases bundle size during development. In production, Terser handles compression after Webpack’s source map composition is complete, so the map remains accurate.

Step 4: Align the Webpack devtool with the loader chain

With the loader chain now passing maps correctly, the devtool setting controls how Webpack writes the final composed map. For production use hidden-source-map to generate an external .map file without a //# sourceMappingURL comment in the bundle (keeping the map private while still usable by APM tools):

// webpack.config.js
module.exports = {
  mode: 'production',
  devtool: 'hidden-source-map',
  optimization: {
    minimizer: [
      new TerserPlugin({
        terserOptions: {
          sourceMap: true,  // Step 4b: Terser must also pass maps through
        }
      })
    ]
  },
  module: {
    rules: [{
      test: /\.js$/,
      exclude: /node_modules/,
      use: {
        loader: 'babel-loader',
        options: {
          sourceMaps: true,
          inputSourceMap: true,
          compact: false,
        }
      }
    }]
  }
};

Step 5: Validate the mapping chain with the source-map library

Before the fix reaches CI/CD, confirm that the produced .map file resolves bundle positions back to original source lines:

// scripts/validate-sourcemap.mjs
import { SourceMapConsumer } from 'source-map';
import { readFileSync } from 'fs';

const rawMap = JSON.parse(readFileSync('./dist/app.bundle.js.map', 'utf8'));

await SourceMapConsumer.with(rawMap, null, (consumer) => {
  const pos = consumer.originalPositionFor({ line: 1, column: 500 });
  console.log('Resolved:', pos);
  // Should print something like:
  // { source: 'webpack://app/src/index.js', line: 12, column: 4, name: 'fetchUser' }
  // NOT:
  // { source: null, line: null, column: null, name: null }
});

If source is null, the map chain is still broken. If source points to a Babel-generated helper like _asyncToGenerator, inputSourceMap is not being honoured—double-check that babel-loader version is 8.2.0 or later, which fixed a regression in inputSourceMap handling.

Verification

Run this Node.js verification script against a freshly built bundle to confirm end-to-end mapping integrity:

// scripts/verify-map-chain.mjs
import { SourceMapConsumer } from 'source-map';
import { readFileSync, existsSync } from 'fs';

const MAP_PATH = './dist/app.bundle.js.map';

if (!existsSync(MAP_PATH)) {
  console.error('ERROR: map file not found at', MAP_PATH);
  process.exit(1);
}

const raw = JSON.parse(readFileSync(MAP_PATH, 'utf8'));

let failures = 0;
let checked = 0;

await SourceMapConsumer.with(raw, null, (consumer) => {
  consumer.eachMapping((m) => {
    if (checked >= 50) return;  // Sample first 50 mappings
    checked++;
    if (!m.source || m.source.includes('webpack/bootstrap')) {
      console.warn(`WARN: mapping at generated ${m.generatedLine}:${m.generatedColumn} resolves to internal bootstrap`);
      failures++;
    }
    // Expect sources like webpack://app/src/...
    if (m.source && !m.source.includes('/src/')) {
      console.warn(`WARN: source "${m.source}" may be transpiled intermediate, not original`);
      failures++;
    }
  });
});

console.log(`Checked ${checked} mappings, ${failures} suspicious.`);
process.exit(failures > 0 ? 1 : 0);

A passing run prints 0 suspicious and exits with code 0. Integrate this as a post-build step in CI to catch regressions before deployment.

Edge Cases & Gotchas

  • @babel/plugin-transform-runtime: This plugin replaces inline helper code (like _asyncToGenerator) with imports from @babel/runtime. The imported helpers are pre-compiled modules that contain no source map of their own, so stack frames inside helpers will always resolve to the @babel/runtime package path. This is expected behavior and not a sign the main map chain is broken—confirm by checking that frames in your code resolve correctly.

  • TypeScript loader before babel-loader: When ts-loader runs before babel-loader (right-to-left, so ts-loader is listed after babel-loader in the use array), ts-loader emits its own intermediate map. inputSourceMap: true in babel-loader is essential here: without it, Babel discards the TypeScript-to-JavaScript map, and the final .map file can only resolve back to the TypeScript output (the .js Babel received), not the original .ts files. Both loaders must emit and accept maps in sequence.

  • Terser plugin consuming maps: Webpack’s TerserPlugin runs after all loaders and performs its own source map composition. It must have sourceMap: true (inside terserOptions) or it will output minified code with no map, overwriting the composed map that the loader chain worked to build. In Webpack 5, TerserPlugin respects the devtool setting by default, but explicitly setting sourceMap: true in the plugin options is the safest cross-version approach.

  • CSS-in-JS with Babel macros: Libraries like styled-components/macro or linaria process template literals via Babel macros at compile time. The macro transformation inserts generated class names and rewrites the template literal AST before @babel/preset-env runs. If the macro does not emit an updated source map after its transformation, the subsequent Babel pass will use an outdated map as its inputSourceMap, producing incorrect line offsets. Check whether your CSS-in-JS library’s Babel plugin explicitly sets shouldPrintComment and emits map data—some do only when sourceMaps: true is already present in the Babel config (Step 1 above handles this).

FAQ

Why does setting devtool: 'source-map' in Webpack not fix the issue on its own? devtool controls how Webpack writes the final map. If babel-loader never emitted an intermediate map, Webpack has no data to compose—it can only map bundle positions back to whatever post-transformation code it received. The devtool setting and the loader options are both required; neither alone is sufficient.

Is there a difference between setting sourceMaps in babel.config.js vs in babel-loader options? Yes—they are independent settings processed by different code paths. babel.config.js applies when Babel is invoked programmatically or via the CLI. babel-loader reads its own options block, which takes precedence over the config file for that specific invocation. Both should be set to true to avoid surprises in different execution contexts (tests, CLI scripts, the Webpack build).

Does this configuration slow down the build significantly? Source map generation adds roughly 10–30% to Babel transform time depending on file size and the number of plugins. The inputSourceMap: true option adds overhead proportional to the size of the incoming map. For large projects, consider using cheap-module-source-map during development (which maps to lines but not columns, and is faster) and reserving hidden-source-map for production builds where accuracy matters for APM symbolication.