Source Maps

Atatus supports source maps to reverse JavaScript minification. This feature makes use of JavaScript Source Maps to translate the minified code references back into the original source. If your source map is publicly web-accessible, we shall download it automatically. Otherwise, you can upload it via our API.

Option A: Automatic source maps download

If your source map is publicly web-accessible, we shall download it automatically. Atatus requires the following to complete the decode process:

  1. There must be a stack trace.
  2. The minified JavaScript files as specified in the stack trace must be publicly accessible.
  3. The map file to be correctly indicated in the minified JavaScript file using a footer comment. As specified in the Source Map Specification, following comment should be at the bottom of your minified JavaScript files:

    //# sourceMappingURL=URL_TO_SOURCE_MAP
  4. The source map file itself must be publicly accessible.

How it works: If we receive a JavaScript error, and we don’t already have the source map for the current code version, we will schedule an attempt to download it. For each stack frame, we’ll first download the minified source file and look for a sourceMappingUrl comment. If it has one, we’ll try to download that file and cache it as the source map. Then for future errors, we’ll use the source map to translate the minified frames back to original frames.

Option B: Uploading source maps

If you don't want to expose your source map or code to the public web, you can upload them directly to Atatus. At the beginning of your deploy script (before the new code is in production), you can upload a source map via our API.

curl \
  -H "Authorization: token YOUR_ADMIN_API_KEY_HERE" \
  -F url= \
  -F sourcemap=@js/ \
  -F version=version_string_here
Name Description
url The full URL of the minified file. Should start with http: or https:, which we'll strip off.
sourcemap The contents of the source map, as a multipart file upload.
version (optional) A string identifying what version of your code this source map is for. It is optional.

Heads up!
Version number is necessary only if the script file name(url) is same across all deployments. You can read When you should use version number. If you set a version number in source map, you must set version in atatus snippet too and vice versa. atatus.setVersion('version_string_here');.

Response Codes
Status Code Meaning
200 Ok - Uploaded successfully
422 Unprocessable Entity - There was an error validating the upload.

You can find Admin API Key in your project settings. We store the source map by project+minified URL+version. If you upload it more than once, each subsequent upload will overwrite the previous data.

You can delete the older source maps through Delete API.

Source Maps for Hybrid Mobile Apps

In hybrid mobile applications, such as Ionic, PhoneGap, Apache Cordova etc., you may find the error stacktraces contain file paths which are different across platforms and devices. This creates complexity when trying to use source maps, because source map requires the minifed URL that is used during upload matches with the URL that would appear in a stacktrace.

For this reason we recommend adding a handler to rewrite file's URLs before the error is reported back to Atatus. An example of such a handler is shown below:

atatus.onBeforeErrorSend(function (payload) {
    var backTraces = payload.backTraces;
    for(var i = 0 ; i < backTraces.length; i++) {
        var backTrace = backTraces[i];
        var filename = backTrace.f;
        var indexOfJsRoot = filename.indexOf("/js/");
        if (indexOfJsRoot !== -1) {
          backTrace.f = '' + filename.substring(indexOfJsRoot);
    return true;

Lets say, an error occuring on file path in Ionic Framework


It will be reported to Atatus as follows

You must uploaded your source map as follows (note that the reported error and the uploaded minified URL are identical

curl \
  -H "Authorization: token YOUR_ADMIN_API_KEY_HERE" \
  -F version=1.0.0 \
  -F url= \
  -F sourcemap=@js/

When you should use version number

Some prefer to have same script file name across all deployments. An e.g. would be, if you decide to have your JavaScript file as

In this case, source map could end up being different for every deployment, depending upon the changes in your main.js file. In order to differentiate these files, you have to set version number in your script side as well as when you upload the source map.

There would be cases where you change your script file name every time you build it, using a version number(random) in the name of the file(e.g. By doing so, every deploy will have a unique script file name. So you do not need to set version number at your script side. Therefore, when you upload the source map also, you should not set the version number.

Please note that, if you do not set a version number in your script but upload a source map with a version number set, then source map will not work. Please take care of this.

Document Sections