Using Source Maps

Honeybadger can automatically translate your production stack traces 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).

Server-Side Source Maps

Most of the same tooling can generate a source map for server-side apps in Node.js. Honeybadger also supports Node's experimental --source-map-support flag as of version 14+. If you run node with --source-map-support (and are generating source maps in your build), your stack traces should be automatically translated before they are sent to Honeybadger.

Related:

Uploading Your Source Map

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

Webpack and Webpacker: Use @honeybadger-io/webpack to automatically upload your source maps during your build.
Rollup and Vite: Use @honeybadger-io/rollup-plugin to automatically upload your source maps during your build.
esbuild: Use @honeybadger-io/esbuild-plugin to automatically upload your source maps during your build.
GitHub Actions: Use github-upload-sourcemap-action to upload your source maps.
Upload API: Other users can use our source map upload API directly. Here's an example using curl:

sh

  

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

Note: In Node.js projects, the minified_url may be a local file path—for instance, the /path/to/dist/main.js on your server.

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.

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.

See Environments and Versions for examples of how to configure the revision automatically at build-time.

Improving error grouping and linking to source code

Honeybadger can separate your application code from your dependencies and vendor code when you tell us the path to your application code in your stack traces; this helps in two major ways:

Your errors will be grouped by where they occurred in your application code, excluding vendor paths (helps significantly with reducing noise)
When using one of our Source Control Integrations (GitHub, GitLab, etc.), files from your application will be automatically linked

To set this up, you need to provide a valid projectRoot option:

js

  

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

When using a source map, projectRoot needs to be the path to your application code inside the source map. If you use Webpack, then you probably want 'webpack:///./' by default. For other module bundlers, the value may be relative to the URL where your assets are hosted (i.e. 'https://www.example.com/assets/').

If your source map includes a relative sourceRoot option ('./source', for example), then the URL would include that in the path: 'https://www.example.com/assets/source/' (this is a more advanced case).

Matching Multiple Files

In some cases you may want to upload the same source map for different URLs or file paths—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

In Node.js, the following path:

/home/*/current/dist/main.js

...matches the following paths:

  
/home/user1/current/dist/main.js
/home/user2/current/dist/main.js

Wildcards are not supported in file names:

  
// invalid (will be an exact match):
https://example.com/assets/*.min.js

// also invalid (will be an exact match):
/home/deploy/current/dist/*.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

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.