JavaScript source map upload

Upload source map files to allow BugSnag to de-obfuscate your JavaScript stack traces.

Overview

For JavaScript code that is minified, source maps can be used to translate back to the original code. See source map support for details.

The source map upload API can be used to upload source maps to BugSnag if they are not publicly hosted.

Uploading source maps

To send source map files to BugSnag, simply POST them to https://upload.bugsnag.com/sourcemap with the following parameters:

  • apiKey - the BugSnag API key that is used in your app.
  • appVersion (optional) - the version of the app that the source map applies to (as set in the JavaScript notifier). If the version isn’t set in the notifier this should be omitted (and the most recent upload will be used for error events).
  • minifiedUrl - The url of the minified JavaScript file that the source map relates to. Asterisks can be used as a wildcard.
  • sourceMap - The source map file.
  • minifiedFile (optional) - the minified JavaScript file that the source map relates to. If this is not provided we will try to obtain the file when an error event is received.
  • projectRoot (optional) - the root path of the project on the filesystem where the source map was built. This will be stripped off from the file name in the displayed stacktraces.
  • overwrite (optional) - this flag denotes whether to overwrite an existing source map for the specified minifiedUrl and appVersion. The default behaviour is to reject uploads for existing versions. Set overwrite=true to allow new uploads to replace existing uploads.
  • <sources> (optional) - each source file referenced by the source map (if the source hasn’t been included in the sourcesContent field of the source map). Each field name should be the URL that would be used to access the file and the value should be the source file. Asterisks in the field name can be used as a wildcard.

Please note that errors that were received before the source maps were uploaded will not be retrospectively de-obfuscated.

cURL example

Here’s an example request with curl:

$ curl --http1.1 https://upload.bugsnag.com/sourcemap \
   -F apiKey=YOUR_API_KEY_HERE \
   -F appVersion=1.2.3 \
   -F minifiedUrl=http://example.com/assets/example.min.js \
   -F sourceMap=@path/to/example.js.map \
   -F minifiedFile=@path/to/example.min.js \
   -F projectRoot=/path/to/project/ \
   -F overwrite=true \
   -F http://example.com/assets/main.js=@path/to/main.js \
   -F http://example.com/assets/utils.js=@path/to/utils.js   

Response codes

If the file is accepted then an HTTP 200 response will be returned with the body “OK”. If not, there are several possible problems which will be indicated with an HTTP 4XX response:

  • 400 - missing required param -indicates that the minifiedUrl parameter is missing.
  • 401 - invalid apiKey - indicates that the provided apiKey doesn’t correspond to a BugSnag project.
  • 409 - duplicate source map file - indicates that BugSnag already has a file for this url and app version. You can ignore this error by using the overwrite parameter.

Frequently asked questions

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 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 notifier 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 Project Settings -> Source maps.

How do I delete source maps I’ve uploaded?

Uploaded source maps can be viewed and deleted by going to Project Settings -> Source maps.

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.

Do you support partial matching/wildcards for the minified URL?

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:

$ curl --http1.1 https://upload.bugsnag.com/sourcemap \
   -F apiKey=YOUR_API_KEY_HERE \
   -F appVersion=1.2.3 \
   -F minifiedUrl=http*://*example.com/assets/example.min.js \
   -F sourceMap=@path/to/example.js.map \
   -F minifiedFile=@path/to/example.min.js \
   -F overwrite=true \
   -F */assets/main.js=@path/to/main.js \
   -F */assets/utils.js=@path/to/utils.js

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.