Using JavaScript source maps to debug errors

Some of the most common questions we get here at Rollbar deal with source maps:

• What are source maps and what do they do?
• How can you enable source mapping?
• Why aren't your source maps working properly?

Let's explore Javascript source maps together, starting with the basics.

{: .highlightbox}
Existing Rollbar users, go to our JavaScript source maps documentation to get started.

As web developers, we have two major goals. First, we want a highly performant website. Second, we want that website to be easy to debug and maintain. Unfortunately, these goals are often at odds with one other. If we minimize our JavaScript, we can achieve some of these goals. Minimizing JavaScript reduces the download size, and the smaller the payload for our website users, the better. If we combine our JavaScript files, we can also reduce the number of http requests.

For a highly performant website, we want to reduce the number of requests the browser has to make in order to fully load, render, and process the page. Furthermore, with transpilers, we can start using new JavaScript features before they are implemented by the browsers.

Unfortunately, minimizing JavaScript also comes with some downsides: it's hard to debug, and we lose original filenames, line numbers, and column numbers. Luckily, source maps solve this problem. A source map is a file that provides a mapping from the minified line and column numbers back to the original file, line, and column. Source maps use Base64 VLQ encoding to reduce the size of the file, while still maintaining all required information.

Using JavaScript source maps in Rollbar

Rollbar supports using source maps to get meaningful stack traces while still using minified JavaScript in production. Once you enable source mapping, you'll see the original source filename, line number, method name, and code snippet in your stack traces, and your error grouping should be more resilient to code changes. In order for the minified-to-source translation to work, we need at minimum a stack trace with column numbers, and a source map file. You'll get a stack trace with column numbers if you give Rollbar an Error object, in a browser that provides column numbers. Your source map file can optionally include any or all of the original source files referenced by the source map. You can include them using the sourcesContent key.

If Rollbar receives an occurrence with certain keys set in it, we will use any source maps that you have provided to us to decode your stack trace. The values that need to be set in your configuration are as follows:

var _rollbarConfig = {
  // add these new params:
  payload: {
    client: {
      javascript: {
        source_map_enabled: true,
        code_version: "some version string, such as a version number or git sha",
        // Optionally have Rollbar guess which frames the error was thrown from
        // when the browser does not provide line and column numbers.
        guess_uncaught_frames: true
      }
    }
  }
};

When we receive an occurrence that has these values, we will look up the source map by filename of the JavaScript file and the code_version specified. Then we will step through all the frames of the stack trace, and convert from the minified location to the original location. We store the source map package by project+version+minified URL. If you upload it more than once, each subsequent upload will overwrite the previous data.

You have two options for providing your source map files to Rollbar: automatic download, or uploading your source maps. We recommend uploading your source map files, and you have two options for how to do this. One is to manually upload your source maps through our UI. Go to your project settings page, and click Source Maps. There, you'll be able to manually select the file you wish to upload. However, our recommended way to upload your source map files is to upload via our API at the beginning of your deploy script (before the new code is in production). Here's an example cURL command for how to do this:

curl https://api.rollbar.com/api/1/sourcemap 
  -F access_token=aaaabbbbccccddddeeeeffff00001111 
  -F version=version_string_here 
  -F minified_url=http://example.com/static/js/example.min.js 
  -F source_map=@static/js/example.min.map 
  -F static/js/site.js=@static/js/site.js 
  -F static/js/util.js=@static/js/util.js

In the above example, our website is http://example.com, we have a minified JavaScript file at http://example.com/js/example.min.js, and we have a source tree like this:

example/
example/static/js/example.min.js
example/static/js/example.min.map
example/static/js/site.js
example/static/js/util.js

If you want to have Rollbar automatically download your files, you need to provide a comment at the bottom of your JavaScript files that points to your source map file (for example: //# sourceMappingURL=URL_TO_SOURCE_MAP). How does automatic downloading work? If we receive a JavaScript error, source maps are enabled, 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 save it as the source map. Then for future errors, we'll use the source map to translate the minified frames back to original frames. This is the easiest method, but not suitable for all cases (such as if you don't want to expose your source map or code to the public web). It is also less reliable than the upload method, since the source map won't be downloaded yet when the first few errors come in. Because of this, we recommend the upload method for production use.

However, if you're using the automatic download method, you can notify our API to trigger a download for each of your minified files. Doing this will reduce the number of errors that the source map isn't applied to, since we'll have a greater chance of downloading the source map before the first error after a deploy occurs. Here's a sample command for this:

curl https://api.rollbar.com/api/1/sourcemap/download
  -F access_token=aaaabbbbccccddddeeeeffff00001111   
  -F version=92429d82a41e930486c6de5ebda9602d55c39986   
  -F minified_url=http://example.com/static/js/example.min.js

Tips and tricks for using source maps with Rollbar

This all seems simple enough, but there are some common problems our users have run into.

• Don't forget to update the version number when you update your JavaScript. If you don't, the filename, line and column numbers will be incorrect.
• The value of minified_url must be the full URL of the minified file. This should start with http: or https:, which we'll strip off.
• Make sure you're not missing one or both of the config params in the on-page JavaScript snippet. Set both payload.client.javascript.source_map_enabled and payload.client.javascript.code_version.
• If you're using the upload method, check to be sure that the code_version used in the on-page snippet matches the version provided in the upload call.
• If you're using the download method, make sure your source map file or minified JavaScript source files are on a host that's reachable from the public internet, and are not gated behind an authorization wall.
• If the JavaScript error that you are expecting to be un-minified does not have column numbers, and you haven't enabled guess_uncaught_frames, we won't be able to apply the source map. We need column numbers to be able to apply the source map without guessing.
• If your source map file combines multiple sub-maps into "sections" within the top level map, we unfortunately don't yet support this source map format (but we are planning to soon).

May all your errors be easy to fix, and if you run into any issues, feel free to contact Customer Support.

If you haven’t already, sign up for a 14-day free trial of Rollbar and let us help you take control of pesky JavaScript errors.