Using Source Maps

Honeybadger can automatically un-minify your code if you provide a source map and make it available either via remote download or by uploading it to Honeybadger.

The best way to let us know about your source map is to upload your files to our servers every time you deploy your code. It's also possible for you to host your source map files yourself along with your production assets. In this case we'll try to download your source maps when an error is reported to us.

Why Source Maps?

Source maps are essential for tracking JavaScript errors. By the time it reaches your end-users, your production JavaScript looks nothing like the JavaScript you wrote when building your app. Modern build processes have multiple stages where your original source code gets optimized to squeeze the best performance from it. That's great for performance, but terrible for debugging (and error tracking).

Source maps are the answer. Source maps allow Honeybadger to show your original source code, even if your production code looks like this:

(function(n){function e(e){for(var r,u,a=e[0],l=e[1],c=e[2],s=0,p=[];s<a.length;s++)u=a[s],o[u]&&p.push(o[u][0]),o[u]=0;});

Generating a Source Map

Most modern build tools can generate source maps for you:

Some source map generators (such as Uglify) embed your original source files in the source map, or have an option to do so. When this option is enabled, Honeybadger will display a source snippet for each expanded line in your stack trace.

Honeybadger does not currently support downloading remote source files (but may in the future—if this is something you're interested in, let us know).

Uploading Your Source Map

Upload your source map(s) every time you deploy your code using one of the following options:

  • Webpack: Use honeybadger-webpack to automatically upload your source maps during your build.

  • Webpacker: See an example Webpacker/Rails app which uploads generated source maps using honeybadger-webpack.

  • Upload API: Other users can use our source map upload API directly. Here's an example using curl:

    curl https://api.honeybadger.io/v1/source_maps \
      -F api_key=PROJECT_API_KEY \
      -F revision=dcc69529edf375c72df39b0e9195d60d59db18ff \
      -F minified_url=https://example.com/assets/application.min.js \
      -F source_map=@path/to/application.js.map \
      -F minified_file=@path/to/application.min.js
    

Versioning Your Project

In Honeybadger, the revision is a unique version for your project; it's what we use to match up the correct source map with the correct error. Every production build of your project must have a unique revision, and the revision of your source map must match the revision configured in honeybadger.js.

Honeybadger.configure({
  // ...the rest of your configuration...
  revision: 'dcc69529edf375c72df39b0e9195d60d59db18ff'
});

If you don't configure the revision, the default value is "master", and Honeybadger may have trouble translating your source maps when your code changes.

Important: Make sure you are using honeybadger.js v0.5.0 or greater since the revision option isn't available in earlier versions.

How to Version Your Project

You can version your project any way you like (as long as it's unique). We prefer Git commit SHAs, since they are always unique for the current build.

The simplest way to get the SHA of the current Git commit is by assigning it to an environment variable before building your project:

HONEYBADGER_REVISION=$(git rev-parse HEAD) \
  npm build # your normal build command (could also be yarn, webpack, etc.)

The HONEYBADGER_REVISION environment variable can be accessed via process.env.HONEYBADGER_REVISION in Node.js, and $HONEYBADGER_REVISION in other shell scripts (such as the curl example).

Matching Multiple URLs

In some cases you may want to upload the same source map for different URLs—for instance, if you serve your files from multiple subdomains, or via both HTTP and HTTPS.

When uploading your source map, an asterisk (*) can be used inside the minified_url to perform a wildcard match. For example, the following will match both the http:// and https:// version of the URL:

http*://example.com/assets/application.min.js

...matches the following URLs:

http://example.com/assets/application.min.js
https://example.com/assets/application.min.js

Hosting Your Source Map

Note: Because we can't prepare your source maps beforehand with this method, it's less reliable—as a result, the first few errors after a deploy may not have your source map applied. We strongly recommend that you upload your source maps to us via our API instead.

In order to make this work you must include a special comment at the bottom of your minified file which points to the corresponding source map file:

// ...minified code...
//# sourceMappingURL=application.min.js.map

See the comment at the bottom of honeybadger.js for a live example. If you upload the original source files along with the source map, Honeybadger will link to those files when displaying the stack trace.

All files must be publically accessible online so that Honeybadger's servers can download and parse them. For the full specification, see the Source Map Revision 3 Proposal.

Authentication

The Honeybadger-Token header can be used to authenticate requests from Honeybadger servers:

Honeybadger-Token: token

You can find your token on the "API Key" tab in your Honeybadger Project's Settings.

Troubleshooting

Check out the Troubleshooting section.