Source Maps

Honeybadger can automatically un-minify your code if you provide a source map along with your minified JavaScript files.

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.

Uploading Your Files to Honeybadger

To upload your source map files to Honeybadger, POST them to https://api.honeybadger.io/v1/source_maps with the following parameters:

api_key (required)
The API key of your Honeybadger project (see the API Key tab in project settings).
minified_url (required)
The URL of your minified JavaScript file in production. * can be used as a wildcard.
minified_file (required)
The minified file itself.
source_map (required)
The source map for your minified file.
revision (optional — default: "master")
The deploy revision (i.e. commit sha) that your source map applies to. This could also be a code version. For best results, set it to something unique every time your code changes. The revision option must also be configured in honeybadger.js.
<additional source files> (optional)
One or more additional source files which may be referenced by your source map. The name should be the URL that would normally be used to access the file, and the value should be the file itself. Many source map generators include the sources in the sourcesContent key inside the source map, so you may not need to send these. * in the name can be used as a wildcard.

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 \
  -F http://example.com/assets/application.js=@path/to/application.js \
  -F http://example.com/assets/utils.js=@path/to/utils.js

Response Codes

The /v1/source_maps API endpoint responds with the following codes:

201 - Created
The files were uploaded successfully.
400 - Bad Request
You're missing a required parameter or have exceeded the maximum file size of 40MB per file (check the error message).
401 - Unauthorized
Your API key is invalid.

Honeybadger stores your source map files using your project, revision, and minified URL. If you upload them more than once, the current upload will overwrite existing data.

In order for future errors to use your new source map, you must configure an identical revision in honeybadger.js:

Honeybadger.configure({
  apiKey: 'project api key',
  environment: 'production',
  revision: 'dcc69529edf375c72df39b0e9195d60d59db18ff'
});

You can also set the revision using a data attribute on the script tag for honeybadger.js:

<script src="//example.com/path/to/honeybadger.min.js" type="text/javascript" data-apiKey="project api key" data-environment="production" data-revision="dcc69529edf375c72df39b0e9195d60d59db18ff"></script>
Important: Make sure you are using honeybadger.js v0.5.0 or greater since the revision option isn't available in earlier versions.

If you don't specify the revision either when uploading your files or in your honeybadger.js configuration, the default is "master". It is highly recommended that you use a unique revision for each deploy as multiple versions of your code may report errors at the same time, and the line mappings are cached by our servers for each minified URL and revision.

You should upload your source map files before the new revision is deployed to production. Errors which occur for each revision will use the source maps which are available at the time, and as already mentioned, the mappings are cached; changing the source map after errors have occured requires deploying a new revision.


Wildcards

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.

An asterisk (*) can be used in URLs to perform a wildcard match. For example, the following example 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 Own Files

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.