Understanding Source-Mapped Stack Traces

Source Maps and Stack Traces

Source maps (.map files) bridge the gap between minified/bundled production code and original source code. They are essential for debugging production JavaScript errors because bundlers like Webpack, Vite, and esbuild produce output that is unreadable without mapping back to the source.

Minified vs Source-Mapped Trace

Without source maps:

TypeError: t is not a function
    at e (main.abc123.js:1:23456)
    at n (main.abc123.js:1:34567)
    at Object.r (main.abc123.js:1:45678)

With source maps applied:

TypeError: fetchUser is not a function
    at UserProfile (src/components/UserProfile.tsx:42:18)
    at Dashboard (src/pages/Dashboard.tsx:28:12)
    at App (src/App.tsx:15:8)

How Source Maps Work

A source map is a JSON file that contains a mapping between positions in the generated code and positions in the original source files. The key fields are:

• sources --- array of original source file paths
• mappings --- Base64 VLQ encoded position mappings
• sourcesContent --- optionally embedded original source code

Source Map in Error Monitoring

Error monitoring services (Sentry, Bugsnag, Datadog) can automatically apply source maps to incoming error reports:

1. Upload source maps during the build/deploy process
2. When an error arrives with a minified stack trace, the service looks up the source map
3. Each frame's file:line:column is mapped back to the original source
4. The enhanced stack trace is displayed in the error dashboard

Common Issues

• Missing source maps --- frames show minified names
• Mismatched versions --- source map from a different build produces wrong mappings
• Inline vs external --- //# sourceMappingURL=... comment must match
• Security concerns --- public source maps expose original code; use upload-based approach instead

Stack Trace Quality Tips

1. Always upload source maps to your error monitoring service
2. Use named functions instead of anonymous arrows for better frame names
3. Set devtool: 'source-map' (not eval-source-map) for production-quality maps
4. Include sourcesContent so the monitoring service can show code context