JavaScript Source Maps

Generating source maps

When generating source maps you normally have the option to include the source content within the source map (sourcesContent field). If this is the case, no separate sources list is required in the upload request.

If the source is external to the source map, the sources either need to be uploaded with the map (recommended) or fetched by Insight Hub when an event is accessed (see docs). When including sources in the upload request, each file is added as a field in the upload request using the remote URL of the file as a key. Asterisks in the field name can be used as a wildcard.

Source maps can also be encoded directly into the JavaScript file rather than linking to a external file, known as inline source maps. This is sometimes used for development purposes or in certain bundling frameworks like Browserify. This format is also supported in Insight Hub.

Wild card usage for minified URLs

The asterisk character can be used as a wildcard for the minifiedUrl field and source file field names. This adds flexibility when matching a source map against an error report and can be useful when the same source map applies to multiple subdomains or protocols.

Multiple wildcards can be used in the same field. Each asterisk matches zero or more characters.

e.g. To use the same source map for `http://staging.example.com/assets/example.min.js` as well as `https://example.com/assets/example.min.js` the following curl command could be used:

If multiple minified URLs in source map uploads match the same minified URL and app version in an error report (due to the use of wildcards) the most recently uploaded source map matching the URL and app version will be used on the error.

If multiple source files in an upload match against a source file url (due to the use of wildcards) the selection of source file will be arbitrary.

Symbolication guide

See our source map guide for a higher-level overview of integrating uploads into your build systems to see full stacktraces for all your releases.

FAQs

Why isn’t the uploaded source map getting applied to my error?

Uploaded source maps get applied to an error based on the url in the stacktrace and the version of the application. The minified JavaScript file also needs to be accessible by BugSnag to ensure that mapping and grouping work correctly.

If the uploaded source map isn’t getting applied correctly you should check the following:

• The minifiedUrl field specified during upload matches the url in the stacktrace. It must exactly match if wildcards haven’t been used or match according to the wildcard logic (above) if they have been used.
• The appVersion field matches the app version (as seen in the app tab on the error) or has been omitted during upload if an app version isn’t being set
• The minified JavaScript file is publicly accessible or has been uploaded using the minifiedFile field
• The error event was received after the source map was uploaded

Why can’t I see the code context for my mapped JavaScript error?

BugSnag needs visibility of the source code in order to display the code context against the lines in the stacktrace.

This can be achieved in the following ways:

• Ensure that the sourcesContent field is populated when generating the source map.
• Allow the source files to be accessible to BugSnag based on the source path specified in the source map
• Upload the source files during source map upload

Why am I getting a response of “Nothing to upload” when uploading my source map?

A 422 (Unprocessable Entity) status code is returned with a message of “Nothing to upload” if the files haven’t been uploaded correctly.

This is often due to missing the @ symbol before the file path for the source map file when using cURL. If the @ symbol is omitted the path to the file is sent rather than the file itself.

What app version should be used during source map upload?

If you are setting an app version in the JavaScript error SDK or are using the Build API to track versions you will need to set the appVersion field to the version being applied.

If you do not set the app version you can omit the appVersion field. This will pick up the latest source map uploaded for the minified url.

Where can I see the details of the source maps that I’ve uploaded?

Uploaded source maps can be viewed and deleted by going to Source maps in the project setting page on your dashboard.

How do I delete source maps I’ve uploaded?

Uploaded source maps can be viewed and deleted by going to Source maps in the project setting page on your dashboard.

Do the uploaded source maps get applied retrospectively to existing errors?

Once a source map is uploaded it will only get applied to new error events. It does not get applied retrospectively to existing errors events.