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.
sourceMap- The source map file.
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
appVersion. The default behaviour is to reject uploads for existing versions. Set
overwrite=trueto 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
sourcesContentfield 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:
minifiedUrlparameter is missing.
apiKeydoesn’t correspond to a Bugsnag project.
If the uploaded source map isn’t getting applied correctly you should check the following:
minifiedUrlfield 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.
appVersionfield 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
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:
sourcesContentfield 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 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.
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.