Lighthouse audit valid-source-maps · Best Practices

"Missing source maps for large first-party JavaScript": how to fix it

Quick answer: Lighthouse flags "Missing source maps for large first-party JavaScript" when your own site serves a script of 500 KiB or more with no source map it can load. Third-party scripts and .sourcesContent warnings do not fail it. Fix it by turning on production source maps in your bundler and deploying the .map files next to the scripts.
View raw .md for LLMs / your notes

Lighthouse prints Missing source maps for large first-party JavaScript when your own site serves a JavaScript file of 500 KiB or more without a source map. A source map links the minified file back to the original source, so stack traces and DevTools show real file names and line numbers instead of a.js:1:48213. Lighthouse also uses source maps to report which modules make a bundle large. In our study of 269 Shopify storefronts, 43 of them (16.0%) failed this audit. This page covers exactly what fails it, the one setting to change in each build tool, and the trade-off if you do not want your source public.

TL;DR

What does "Missing source maps for large first-party JavaScript" mean?

Lighthouse checks every script on the page and records whether it has a source map. Per the audit source, the audit fails only when a script meets all three conditions:

ConditionMeaning
First-partyServed from your own site or entity, not a vendor domain
Large500 KiB or more of script content
No source mapNo sourceMappingURL reference, or the map could not be loaded

The table lists scripts with their map URL and any errors. Two messages appear in the error column:

The audit carries no weight in the Best Practices score in Lighthouse 13. It is a debugging and diagnostics check. Fix it because it makes production errors readable and lets Lighthouse attribute bundle size to modules, not to raise a score.

Why does a 500 KiB first-party script matter?

Two reasons. First, a large minified bundle is where production bugs hide, and without a map every stack trace points at line 1 of one long file. Second, Lighthouse and DevTools use source maps to break a bundle into modules. With a map, Reduce unused JavaScript and the DevTools Coverage and Performance panels can name the library that wastes bytes. Without it, they can only name the bundle.

A first-party script over 500 KiB is also worth questioning on its own. See Reduce unused JavaScript and Total Blocking Time.

How do I add source maps in my build tool?

Each bundler has one setting. Turn it on for production builds and deploy the .map files with the scripts.

ToolSetting
Vitebuild: { sourcemap: true } in vite.config.js
webpackdevtool: 'source-map' in the production config
Next.jsproductionBrowserSourceMaps: true in next.config.js
Rollupoutput: { sourcemap: true }
esbuild--sourcemap flag, or sourcemap: true in the build API
Angular"sourceMap": true under the production configuration in angular.json
Create React AppSource maps are on by default; check that GENERATE_SOURCEMAP=false is not set

The bundler adds a comment at the end of each script, such as //# sourceMappingURL=app.3f9c1.js.map, and the browser loads the map from that URL. Upload the .map files to the same place as the scripts. A map that returns 404 counts as missing.

// vite.config.js
export default {
  build: {
    sourcemap: true,
  },
};

What if I do not want my source code public?

A public source map exposes your original code, comments included. That is a real trade-off, and you have three options:

  1. Publish the maps. Your client JavaScript is already public in minified form; the map makes it readable. For most sites the debugging value is worth it. Keep secrets out of client code either way, because minification never protected them.
  2. Hidden source maps. Build the maps but omit the sourceMappingURL comment ('hidden-source-map' in webpack, sourcemap: 'hidden' in Vite), then upload the maps only to your error tracker, such as Sentry. Your errors become readable, but Lighthouse cannot find the maps, so the audit keeps failing. That is an acceptable outcome for a check with no score weight.
  3. Restrict access to the .map files at the server or CDN. Lighthouse loads maps like a visitor does, so a blocked map also counts as missing.

Pick option 1 to clear the audit, option 2 if code privacy matters more than this check.

Can I fix this for Shopify or WordPress?

Usually you do not need to. Theme JavaScript on Shopify and WordPress is rarely 500 KiB or more, and app or plugin scripts served from a vendor domain are third-party, which this audit ignores. When it fails on these platforms, the script is normally a custom bundle the theme developer built. Turn on source maps in that build and upload the .map file to the theme assets folder or the same server path. On Shopify Hydrogen, Vite settings apply.

How do I verify the fix?

  1. Re-run Lighthouse. Missing source maps for large first-party JavaScript should change to "Page has valid source maps", and the table should show a map URL for each large script.
  2. In DevTools, open the Sources panel. Your original files should appear under the page, with real folder names, next to the bundled script.
  3. Open the map URL from the table in a new tab. It should return JSON, not a 404 or an access error.

What mistakes should I avoid?


Audit your URL at https://lighthouse-md.com.

Audit your page now

Paste your URL, get scores plus a CLAUDE.md plan for Claude Code.

Run audit →
Add us as a preferred source on Google

One click, and Google shows more of lighthouse-md.com in your search results.