What are Debug IDs
This documentation provides an in-depth look at Debug IDs, explaining how they work and why Sentry recommends using them. Visit Uploading Source Maps if you're looking for our guides on how to upload source maps.
Modern web applications often use some kind of build process when using JavaScript. This build process takes some input JavaScript, transforms it in some way, then outputs JavaScript that is served alongside the website. Some example transformations include minifying JavaScript code (so the final JavaScript bundle is smaller and faster to load) or removing TypeScript types (only JavaScript can run on the browser).
As a result, the JavaScript code running in production is typically not the same as the code written by the developer in the source editor. Instead, it has undergone several transformations, such as minification, transpilation, downcompilation, bundling, polyfilling, and others, aimed at improving performance and ensuring cross-browser compatibility. Some common tools that transform code in such ways are Babel, Vite, Webpack, Rollup, Terser, or SWC - which are often used by higher-level tools like Next.js, Nuxt, Create React App, and similar.
Stack traces are essential to debug errors, but stack traces that come from generated JavaScript are often unreadable or unusable! They look nothing like the code you wrote and you can't connect them to your source code repository.
To ensure Sentry (and other tools) can provide stack traces that are both readable and useful, you'll want to generate and use source maps. Source maps are additional pieces information (often stored as files) that map the transformed JavaScript back to the original code. This allows Sentry to associate the error with your original source, which means you’ll get stack traces that look like the code you wrote, not the code you generated.
To connect source maps to a JavaScript file, we relied on filenames, but these often were unreliable. For example, when you changed the subpath of where your javascript files are served it would mean that the filenames no longer match and the corresponding sourcemap would not be able to be found by Sentry.
//# source mappingURL=http://example.com/path/to/your/source-map.js.map
Given the url-based filename approach was unreliable, we came up with Debug IDs.
Inspired by approaches in native language ecosystems, Debug IDs are globally unique ids that identify a transformed JavaScript file and its associated source map.
When using sentry-cli or Sentry plugins for Webpack, Vite, or Rollup, Debug IDs are deterministically generated based on the source file contents. Note that deterministic Debug IDs for esbuild are not currently supported.
This approach is Sentry's recommended and most reliable method for associating minified JavaScript files with their original source code, making it easier to trace errors back to their source. Because debug IDs will generally change across releasess if the file content is changed creating a release is no longer required. Release names were previously used to disambiguate sourcemaps with the same name across deployments.
If you want to learn more about the rationale behind Debug IDs, we suggest taking a look at our engineering blog.
To use Debug IDs, ensure that you're using Sentry's SDK version 7.47 or higher. Once you're on a supported version, follow the steps outlined below:
A globally unique Debug ID is generated: During the build process, if you are using one of Sentry's Bundler Plugins or Sentry CLI a Debug ID is generated, which is globally unique and ideally deterministic.
Debug IDs are embedded in minified files: Each minified JavaScript file includes a special comment, such as
//# debugId=DEBUG_ID, whereDEBUG_IDis the unique identifier generated in the previous step.The same Debug ID is added to source maps: Source maps also include the same Debug ID as a new attribute, linking the minified JavaScript file to its corresponding source map.
Stack traces in Sentry link the Debug ID: When an error occurs, Sentry's event contains the Debug ID, which allows Sentry to automatically link the error to the correct source map. This ensures the stack trace is resolved back to the original source code, providing you with clearer and more accurate debugging information—even if the JavaScript has been minified or transformed.
Unminifying your code is essential for effective debugging. While there are other legacy ways to achieve this at Sentry, using Debug IDs are recommended by Sentry as it is the most reliable method. By unminifying your code, you get much clearer stack traces when errors occur. Instead of seeing obfuscated code, you'll see the exact code you originally wrote, making it far easier to understand and resolve issues. Below are examples that demonstrates the difference:
Artifacts including Debug IDs have a retention period of 90 days, using a time to idle expiration mechanism. This means that uploaded Debug IDs are retained for as long as they are actively being used for event processing. Once an ID has not been used to process incoming events for at least 90 days, it will automatically expire and be eligible for deletion.
Since you might still want to know to which release an specific Debug ID is connected to, we designed a new way to still associate a release to your bundle.
The new Debug ID format supports a new kind of association to a release and optionally dist, known as weak release association. This type of association will not require the creation of a release before uploading source maps and will consequently allow the creation of a release as a separate step down the pipeline.
With an associated release and optionally dist you will be able to quickly go to the Debug ID from your release in Sentry, without having to worry about which Debug ID was used for your errors.
Our documentation is open source and available on GitHub. Your contributions are welcome, whether fixing a typo (drat!) or suggesting an update ("yeah, this would be better").