Sourcemaps
Sourcemaps describe how positions in JavaScript files relate to the original source. Bugsink uses them so that a stack
trace can point at the right line and display nearby code. This is essential when JavaScript is minified or bundled:
an error like captureException.min.js:2:143 is unreadable without a map.
Bugsink also supports a less obvious use: uploading a map for plain, unminified JavaScript. Since browsers don’t actually allow the running script to access its own source code (for security reasons), SDKs can’t recover context lines on their own. Bugsink lets you upload an identity sourcemap, which simply maps each location back to itself and embeds the full file. This approach keeps error reports clear without adding network lookups or release bookkeeping.
Setting it up
You’ll need Bugsink 1.5 or newer and sentry-cli.
For a minified build, create a sourcemap, inject debug IDs, and upload:
uglifyjs captureException.js -o captureException.min.js --source-map url=captureException.min.js.map,includeSources
sentry-cli sourcemaps inject .
SENTRY_AUTH_TOKEN=yourtokengoeshere sentry-cli --url https://yourbugsinkinstance/ sourcemaps --org bugsinkhasnoorgs --project=ignoredfornow upload .
For unminified scripts, generate an identity map and upload it the same way:
pip install ecma426 # installs identity-sourcemap utility
identity-sourcemap captureException.js
sentry-cli sourcemaps inject captureException.js captureException.js.map
SENTRY_AUTH_TOKEN=... sentry-cli --url https://yourbugsinkinstance/ sourcemaps --org bugsinkhasnoorgs --project=ignoredfornow upload captureException.js.map
Bugsink implements only the standard upload endpoints used by sentry-cli.
Bundlers or frameworks that call those endpoints will work, but Bugsink doesn’t guarantee support for tools that require additional upload APIs beyond this flow.
How it works
sentry-cli sourcemaps inject adds a debug ID to
both the script and its map. Bugsink stores uploaded files as an artifact bundle. When an event arrives, the debug ID in
the payload selects the right source – no guessing based on filenames, no releases to configure.
Matching by the embedded ID is deliberate. Other trackers often guess based on release names or file paths, which can break when files move or builds differ between environments. Bugsink skips that entire layer: once a bundle is uploaded, the debug ID is the only key needed to resolve a stack frame.
Fetching scripts from URLs is deliberately unsupported. Uploading artifacts is deterministic and avoids security problems such as server-side request forgery.
Identity maps use the same mechanism. Once uploaded they behave exactly like maps for minified code: Bugsink looks up
the artifact by its debug ID and shows the sourcesContent embedded in the map. There’s no special case on the server
side, only a different kind of map on upload.
Further work (tracked in #150) focuses on testing with more build tools and improving handling of very large bundles, but the core lookup path — debug ID → artifact bundle → source lines — is already stable.
Troubleshooting
If an upload fails, run sentry-cli with --loglevel=debug to see details. Confirm that the script contains the
debugId comment added by inject, and that the map (or identity map) includes the full source in sourcesContent.