Upload source map files to allow BugSnag to de-obfuscate your JavaScript stack traces.
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.
To send source map files to BugSnag, simply POST them to https://upload.bugsnag.com 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.
Here’s an example request with curl:
$ curl --http1.1 https://upload.bugsnag.com/ \
-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
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:
minifiedUrl parameter is missing.apiKey doesn’t correspond to a BugSnag project.overwrite parameter.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:
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.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 setminifiedFile fieldBugSnag 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:
sourcesContent field is populated when generating the 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.
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.
Uploaded source maps can be viewed and deleted by going to Project Settings -> Source maps.
Uploaded source maps can be viewed and deleted by going to Project Settings -> Source maps.
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.
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/ \
-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.