How to Upload Source Maps to Your Error Tracker

Your production JavaScript is minified, but the errors your users hit are not. A stack trace pointing at bundle-a3f2.js:1:8472 tells you nothing. Upload source maps to transform that line number back to your actual code — a TypeScript component, a React hook, the exact line you need to fix. Automating the upload in CI means every deploy ships readable stack traces, and bugs that would have been mysteries become one-click fixes.

This guide walks you through the why, how, and the patterns that work across every build tool.

Why minified stack traces are worthless

Without source maps, your error tracker shows you this:

TypeError: Cannot read properties of undefined (reading 'slice')
  at h.render (bundle-a3f2.js:1:8472)
  at performUnitOfWork (bundle-a3f2.js:1:9284)

You know something broke, but not where. The line numbers are from the minified bundle, not your source. It could be anywhere in your codebase, in any function with a closure. Hunting takes hours.

With source maps applied, the same error becomes:

TypeError: Cannot read properties of undefined (reading 'slice')
  at UserList.tsx:42:17 (in render)
  at React.performUnitOfWork (react.js:1049:3)

Now it's specific. You can navigate straight to line 42 of UserList.tsx, see the exact code, and fix it in minutes.

What source maps are (briefly)

A source map is a JSON file that maps positions in minified code back to positions in your original source. Webpack, Vite, Next.js, and every other modern bundler can generate them. The file is separate from your bundle — bundle.js ships to users, bundle.js.map stays on your server.

Your error tracker (LightTrace, Sentry, others) uses the map to de-minify stack traces after the fact. No runtime overhead, no bloat in production. Learn more about how source maps work.

Automating source map upload in CI

The pattern is the same across every build tool:

1. Build your app with source maps enabled.
2. Upload the maps to your error tracker during CI/CD.
3. Deploy your minified code.
4. The error tracker keeps the maps and uses them to de-minify incoming errors.

LightTrace is Sentry-SDK-compatible, so you use the standard Sentry CLI to upload. Add it to your pipeline:

npm install --save-dev @sentry/cli
# or
pip install sentry-cli

Configure your auth token (store it in CI secrets):

export SENTRY_AUTH_TOKEN="your-auth-token"
export SENTRY_ORG="your-org"
export SENTRY_PROJECT="your-project"
export SENTRY_URL="https://your-lighttrace-host"

Then upload after building:

sentry-cli releases files upload-sourcemaps \
  --release "web@1.0.0" \
  dist/

That command scans dist/ for .js and .map files, uploads them, and associates them with your release tag.

Tool-specific setup

Next.js

Next.js builds source maps by default in production. Upload them during your deploy:

# next.config.js
module.exports = {
  productionBrowserSourceMaps: true,
};

In your CI pipeline (GitHub Actions example):

- name: Build
  run: npm run build

- name: Upload source maps
  env:
    SENTRY_AUTH_TOKEN: ${{ secrets.SENTRY_AUTH_TOKEN }}
  run: |
    npx sentry-cli releases files upload-sourcemaps \
      --release "web@${{ github.sha }}" \
      .next/static/

See our Next.js source maps guide for a deeper walkthrough.

Vite

Vite can generate maps for production builds. Enable them in your config:

// vite.config.ts
export default defineConfig({
  build: {
    sourcemap: true,
  },
});

After npm run build, your dist/ folder will have .js and .map files. Upload them:

npx sentry-cli releases files upload-sourcemaps \
  --release "web@$(cat package.json | jq -r .version)" \
  dist/

Our Vite source maps guide covers more options.

Webpack

Configure webpack to emit maps:

// webpack.config.js
module.exports = {
  mode: "production",
  devtool: "source-map", // or "hidden-source-map"
  // ... rest of config
};

The hidden-source-map option generates maps but doesn't reference them in the built .js files — safer for production. Upload in CI:

npx sentry-cli releases files upload-sourcemaps \
  --release "your-release-tag" \
  build/

Read more in our Webpack source maps guide.

Versioning and releases

Tying source maps to a release is critical. Your error tracker needs to know which version of the map to apply to each incoming error.

Use a clear release tag: web@1.2.3, backend@2024-07-03, mobile@build-1847. Then upload with that same tag:

sentry-cli releases files upload-sourcemaps \
  --release "web@1.2.3" \
  dist/

When an error arrives from version web@1.2.3, the tracker knows exactly which maps to use.

Cleanup and security

Source maps can be large (often 2-3x the minified bundle). After uploading, clean them up locally before deploying:

npm run build
sentry-cli releases files upload-sourcemaps --release "web@1.0.0" dist/
rm -rf dist/**/*.map  # Clean up maps before shipping
npm run deploy

Also make sure .map files never reach your production server. Add them to .gitignore and your build-artifact rules:

# .gitignore
dist/**/*.map
build/**/*.map
.next/static/**/*.map

And configure your HTTP server to never serve them publicly. If someone downloads your maps, they can read your full source. Keep them server-side only.

Troubleshooting missing maps

If stack traces are still minified after upload:

1. Check the release tag. The error's release must match what you uploaded. Look at the error details in your dashboard — the SDK reports which release it came from.
2. Verify the upload. Run sentry-cli releases files list <release> to see what was uploaded.
3. Check file paths. The source map filename must match the minified file. If you're uploading main-abc123.js.map but your HTML loads main.js, they won't connect.

The guide to debugging minified JavaScript has more debugging strategies.

Once source maps are flowing, your team goes from guessing what broke to reading the exact line that failed. The setup takes an hour; the payoff is faster every fix you'll ship.