Error tracking: how do source maps work for my JS errors?

When a JavaScript error happens in production, the stack trace points into your minified bundle (main.a8f42b.js:1:42819). That's useless for debugging. Source maps are the JSON files your bundler emits that tell us how to translate those line/column numbers back to your original source.

How source maps work in Zenovay

1. Your build produces a bundle (e.g. main.a8f42b.js) and a corresponding source map (main.a8f42b.js.map).
2. You upload the source map to Zenovay — either via the CLI, the API, or your CI integration.
3. When an error arrives, the tracker matches the bundle URL + the release tag against your uploaded maps.
4. The dashboard displays the original file, line, column, and a code snippet.

Source maps are stored against a release identifier — either a Git SHA, a semver tag, or any string you set. If the release doesn't match an uploaded map, you'll see the minified line in the dashboard.

Uploading source maps

Via the CLI

npx @zenovay/cli sourcemaps upload \
  --release v2.4.1 \
  --bundle https://example.com/static/main.js \
  --map ./dist/main.js.map

Via the API

POST https://api.zenovay.com/v1/sourcemaps with multipart form fields release, bundle_url, and map (the file). Authentication is the same zv_* API key you use elsewhere.

Via CI (recommended)

Add the upload step to your post-build pipeline so every release ships with maps. The CLI exits 0 if the upload succeeds, non-zero otherwise — so a failed upload fails your build.

Setting the release on the tracker

For the matching to work, the tracker has to know which release to tag errors with:

<script
  src="https://api.zenovay.com/_z/script.js"
  data-tracking-code="zv_abc123"
  data-release="v2.4.1"
></script>

Or set it dynamically from your build:

<script>
  window.ZENOVAY_RELEASE = process.env.RELEASE_TAG;
</script>

Verifying it works

1. Upload a map, then trigger a known error in production.
2. Open the error in Errors → Issues.
3. The stack-trace section should show your original file path (e.g. src/components/Checkout.tsx:42) and a 5-line code preview.

If it still shows the minified line, check:

• The data-release attribute matches the release you uploaded under.
• The bundle_url you uploaded matches the <script src> exactly (including hash).
• The .map file isn't truncated (a partial upload can fail silently).

Privacy

Source maps contain your full original code. They're stored privately, scoped to your team, and never served publicly. If you'd rather keep the maps off our servers entirely, you can run a local stack-trace resolver — see the docs at docs.zenovay.com.

Related reading

• JavaScript errors overview
• Reading stack traces
• Error groups