Hosting / Uploading

Source maps can be either:

  1. Served publicly over HTTP alongside your source files.
  2. Uploaded directly to Sentry (recommended).

Hosting Source Map Files

By default, Sentry will look for source map directives in your compiled JavaScript files, which are located on the last line and have the following format:

//# sourceMappingURL=<url>

When Sentry encounters such a directive, it will resolve the source map URL relative the source file in which it is found, and attempt an HTTP request to fetch it.

So for example if you have a minified JavaScript file located at http://example.org/js/app.min.js. And in that file, on the last line, the following directive is found:

//# sourceMappingURL=app.js.map

Sentry will attempt to fetch app.js.map from http://example.org/js/app.js.map.

Alternatively, during source map generation you can specify a fully qualified URL where your source maps are located:

//# sourceMappingURL=http://example.org/js/app.js.map

While making source maps available to Sentry from your servers is the easiest integration, it is not always advisable:

  • Sentry may not always be able to reach your servers.
  • If you do not specify versions in your asset URLs, there may be a version mismatch
  • The additional latency may mean that source mappings are not available for all errors.

For these reasons, it is recommended to upload source maps to Sentry beforehand (see below).

Uploading Source Maps to Sentry

Except for webpack, the recommended way to upload source maps is using Sentry CLI. If you have used Sentry Wizard to set up your project, it has already created all necessary configuration to upload source maps. Otherwise, follow the CLI configuration docs to set up your project.

Sentry uses Releases to match the correct source maps to your events. To create a new release, run the following command (e.g. during publishing):

$ sentry-cli releases new <release_name>

Note the release name must be unique within your organization and match the release option in your SDK initialization code. Then, use the upload-sourcemaps command to scan a folder for source maps, process them and upload them to Sentry:

$ sentry-cli releases files <release_name> upload-sourcemaps /path/to/files

This command will upload all files ending in .js and .map to the specified release. If you wish to change these extensions – e.g. to upload typescript sources – use the --ext option:

$ sentry-cli releases files <release_name> upload-sourcemaps --ext ts --ext map /path/to/files

Until now, the release is in a draft state (“unreleased”). Once all source maps have been uploaded and your app has been published successfully, finalize the release with the following command:

$ sentry-cli releases finalize <release_name>

For convenience, you can alternatively pass the --finalize flag to the new command which will immediately finalize the release.

Note: You dont have to upload the source files (ref’d by source maps), but without them the grouping algorithm will not be as strong, and the UI will not show any contextual source.

Additional information can be found in the Releases API documentation.