Introduction

Sourcemaps map minified production JavaScript back to the original source code, enabling debugging in browser DevTools. When sourcemaps fail to load, the browser shows minified code with unreadable variable names:

bash
DevTools failed to load source map: Could not load content for
https://example.com/static/js/main.a1b2c3.js.map:
HTTP error: status code 404, net::ERR_HTTP_RESPONSE_CODE_FAILURE

Without sourcemaps, stack traces in error monitoring tools (Sentry, LogRocket) reference minified line numbers that are nearly impossible to trace.

Symptoms

  • Browser DevTools shows minified code instead of original source
  • "DevTools failed to load source map" warning in the console
  • Error monitoring tools report stack traces with minified file names and line numbers
  • Sourcemap URL returns 404 from the CDN or server
  • Sourcemap loads but shows incorrect source file mappings

Common Causes

  • Sourcemap files not uploaded to the CDN or server during deployment
  • Server returns 404 for .js.map files due to MIME type or routing configuration
  • Sourcemap URL in the minified JS file points to wrong path after CDN deployment
  • CORS headers on sourcemap files block cross-origin loading
  • Build tool configured with hidden-source-map or nosources-source-map which limits mapping data

Step-by-Step Fix

  1. 1.Verify sourcemaps are generated in the build output:
  2. 2.```bash
  3. 3.ls -la dist/static/js/*.map
  4. 4.# Should show files like main.a1b2c3.js.map
  5. 5.`
  6. 6.Check that the minified JS file references the sourcemap:
  7. 7.```bash
  8. 8.tail -1 dist/static/js/main.a1b2c3.js
  9. 9.# Should end with: //# sourceMappingURL=main.a1b2c3.js.map
  10. 10.`
  11. 11.Configure the build tool to generate accessible sourcemaps. For Webpack:
  12. 12.```javascript
  13. 13.module.exports = {
  14. 14.devtool: 'source-map', // Full sourcemaps (not hidden or nosources)
  15. 15.output: {
  16. 16.publicPath: '/static/',
  17. 17.},
  18. 18.};
  19. 19.`
  20. 20.Ensure sourcemaps are deployed alongside the JavaScript files. If using a CDN upload step:
  21. 21.```bash
  22. 22.aws s3 sync dist/ s3://my-cdn-bucket/ --exclude "*" --include "*.js.map"
  23. 23.`
  24. 24.Configure server MIME type for sourcemaps:
  25. 25.```nginx
  26. 26.location ~* \.js\.map$ {
  27. 27.add_header Content-Type application/json;
  28. 28.add_header Access-Control-Allow-Origin *;
  29. 29.add_header Cache-Control "public, max-age=31536000, immutable";
  30. 30.}
  31. 31.`
  32. 32.For Apache:
  33. 33.```apache
  34. 34.AddType application/json .map
  35. 35.<FilesMatch "\.js\.map$">
  36. 36.Header set Access-Control-Allow-Origin "*"
  37. 37.</FilesMatch>
  38. 38.`
  39. 39.Fix sourcemap URL when behind a CDN. If the sourcemap URL in the minified file is relative but the file is served from a CDN, use SourceMapDevToolPlugin:
  40. 40.```javascript
  41. 41.const webpack = require('webpack');
  42. 42.module.exports = {
  43. 43.plugins: [
  44. 44.new webpack.SourceMapDevToolPlugin({
  45. 45.filename: '[file].map',
  46. 46.publicPath: 'https://cdn.example.com/static/js/',
  47. 47.}),
  48. 48.],
  49. 49.};
  50. 50.`

Prevention

  • Automate sourcemap deployment as part of your CI/CD pipeline - never deploy JS without corresponding .map files
  • Use devtool: 'hidden-source-map' for production if you only need sourcemaps for error reporting tools (Sentry uploads them directly without exposing to browsers)
  • Configure Sentry or similar tools to upload sourcemaps during build: sentry-cli sourcemaps upload ./dist
  • Test sourcemap loading after every deployment using a browser's DevTools Sources panel
  • Monitor sourcemap 404 rates in your server access logs: grep ".js.map" /var/log/nginx/access.log | grep " 404 " | wc -l
  • Document the sourcemap deployment path in your runbook for team members