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.
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 fails it: A first-party script, at least 500 KiB, with no source map Lighthouse can load.
- What does not fail it: Third-party scripts, small scripts, and warnings such as "missing 1 item in
.sourcesContent". Those show in the table but do not fail the audit. - Fix: Turn on production source maps in your bundler and deploy the
.mapfiles next to the scripts.
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:
| Condition | Meaning |
|---|---|
| First-party | Served from your own site or entity, not a vendor domain |
| Large | 500 KiB or more of script content |
| No source map | No 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:
- "Large JavaScript file is missing a source map": this row is why the audit failed.
- "Warning: missing N items in
.sourcesContent": the map exists but does not embed some original sources. This is a warning only. It does not fail the audit.
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.
| Tool | Setting |
|---|---|
| Vite | build: { sourcemap: true } in vite.config.js |
| webpack | devtool: 'source-map' in the production config |
| Next.js | productionBrowserSourceMaps: true in next.config.js |
| Rollup | output: { sourcemap: true } |
| esbuild | --sourcemap flag, or sourcemap: true in the build API |
| Angular | "sourceMap": true under the production configuration in angular.json |
| Create React App | Source 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:
- 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.
- Hidden source maps. Build the maps but omit the
sourceMappingURLcomment ('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. - Restrict access to the
.mapfiles 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?
- 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.
- In DevTools, open the Sources panel. Your original files should appear under the page, with real folder names, next to the bundled script.
- 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?
- Building maps but not deploying them. The comment points at a URL that returns 404, which counts as missing. Check that your deploy step uploads
.mapfiles. - Maps out of sync with the script. A cached old map for a new bundle gives wrong line numbers. Fingerprint map file names the same way as the scripts.
- Treating the
.sourcesContentwarning as a failure. It is a warning only. Fix it by setting your bundler to embed sources if you want the full files in DevTools. - Chasing third-party rows. Vendor scripts without maps appear in the table but never fail this audit.
Related audits
- Reduce unused JavaScript: source maps let it name the module that wastes bytes
- Total Blocking Time: what a large bundle costs when it runs
- Legacy JavaScript: polyfills that make bundles larger than they need to be
- Browser errors were logged to the console: the errors source maps make readable
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.