--- title: "Legacy Uploading Methods" description: "Learn about how to upload source maps with older SDKs and Sentry tools." url: https://docs.sentry.io/platforms/javascript/guides/react-router/sourcemaps/troubleshooting_js/legacy-uploading-methods/ --- # Legacy Uploading Methods | Sentry for React Router Framework Sentry moved to a new process for handling source maps. We call this process "source mapping with debug IDs". This process requires you to use updated Sentry dependencies. We know this isn't always possible, so this page explains how to upload source maps without debug IDs. ## [When to use this guide](https://docs.sentry.io/platforms/javascript/guides/react-router/sourcemaps/troubleshooting_js/legacy-uploading-methods.md#when-to-use-this-guide) Use the guide on this page if you're using one of the following: * JavaScript SDK version `7.46.0` or lower * `@sentry/webpack-plugin` package version `1.x` or lower * `sentry-cli` version `2.16.1` or lower * Sentry self-hosted or single-tenant on version `23.6.1` or lower If all of your Sentry dependencies are on more up-to-date versions than in the list above, we recommend using the regular [Source Maps](https://docs.sentry.io/platforms/javascript/guides/react-router/sourcemaps.md) guide. If you're using one or more of these older versions of the tools, you can still upload source maps; however, the process will be different. Instead of using debug IDs, you'll use [Releases](https://docs.sentry.io/product/releases.md) to match an event's stack frame with its corresponding minified source and source map file (known as artifacts). To use this guide, scroll down to the section that corresponds to the tooling you're using, and follow the steps in that section: * `sentry-cli` * Sentry webpack plugin Version 1.x * Sentry Bundler Plugins on Version 2.x The final "[Verify Artifacts Were Uploaded](https://docs.sentry.io/platforms/javascript/guides/react-router/sourcemaps/troubleshooting_js/legacy-uploading-methods.md#verify-artifacts-were-uploaded)" section applies to each type of tooling. ## [Uploading using `sentry-cli`](https://docs.sentry.io/platforms/javascript/guides/react-router/sourcemaps/troubleshooting_js/legacy-uploading-methods.md#uploading-using-sentry-cli) ### [1. Update SDK Options](https://docs.sentry.io/platforms/javascript/guides/react-router/sourcemaps/troubleshooting_js/legacy-uploading-methods.md#1-update-sdk-options) To match events with the correct release, you must provide a `release` property in the SDK options: ```javascript Sentry.init({ // This value must be identical to the name you give the release that you // create below using `sentry-cli`. release: "", }); ``` ### [2. Create a New Release](https://docs.sentry.io/platforms/javascript/guides/react-router/sourcemaps/troubleshooting_js/legacy-uploading-methods.md#2-create-a-new-release) You must first create a release with `sentry-cli`. The release name must be unique within your organization: ```bash sentry-cli releases new ``` ### [3. Upload Artifacts](https://docs.sentry.io/platforms/javascript/guides/react-router/sourcemaps/troubleshooting_js/legacy-uploading-methods.md#3-upload-artifacts) Next, upload your artifacts (minified sources and source maps): ```bash sentry-cli sourcemaps upload --release= /path/to/directory ``` ## [Uploading using Sentry Webpack Plugin Version 1.x](https://docs.sentry.io/platforms/javascript/guides/react-router/sourcemaps/troubleshooting_js/legacy-uploading-methods.md#uploading-using-sentry-webpack-plugin-version-1x) Assuming you have the `@sentry/webpack` package installed on version `1.x`, you can learn more on how to configure the plugin in the [Sentry webpack plugin v1 documentation](https://github.com/getsentry/sentry-webpack-plugin#readme). Example: `webpack.config.js` ```javascript const SentryWebpackPlugin = require("@sentry/webpack-plugin"); module.exports = { // ... other config above ... devtool: "hidden-source-map", // Source map generation must be turned on ("hidden-source-map", "source-map", etc.) plugins: [ new SentryWebpackPlugin({ org: "___ORG_SLUG___", project: "___PROJECT_SLUG___", // Specify the directory containing build artifacts include: "./dist", sourcemaps: { // As you're enabling client source maps, you probably want to delete them after they're uploaded to Sentry. // Set the appropriate glob pattern for your output folder - some glob examples below: filesToDeleteAfterUpload: [ "./**/*.map", ".*/**/public/**/*.map", "./dist/**/client/**/*.map", ], }, // Auth tokens can be obtained from // https://sentry.io/orgredirect/organizations/:orgslug/settings/auth-tokens/ authToken: process.env.SENTRY_AUTH_TOKEN, // Optionally uncomment the line below to override automatic release name detection // release: process.env.RELEASE, }), ], }; ``` The Sentry webpack plugin will automatically inject a release value into the SDK so you must either omit the `release` option from `Sentry.init` or make sure `Sentry.init`'s `release` option matches the plugin's `release` option exactly: ```javascript Sentry.init({ dsn: "___PUBLIC_DSN___", // When using the plugin, either remove the `release`` property here entirely or // make sure that the plugin's release option and the Sentry.init()'s release // option match exactly. // release: "my-example-release-1" }); ``` ## [Uploading using Sentry Bundler Plugins on Version `2.x`](https://docs.sentry.io/platforms/javascript/guides/react-router/sourcemaps/troubleshooting_js/legacy-uploading-methods.md#uploading-using-sentry-bundler-plugins-on-version-2x) If you're using * Sentry self-hosted or single-tenant on version `23.6.1` or lower * or the Sentry JavaScript SDK on version `7.46.0` * or esbuild with `splitting: true` you'll need to configure the bundler plugins with the `release.uploadLegacySourcemaps` option. This applies when using the following packages on version `2.x` and above: * `@sentry/webpack-plugin` * `@sentry/vite-plugin` * `@sentry/esbuild-plugin` * `@sentry/rollup-plugin` Example of using the `release.uploadLegacySourcemaps` option: `webpack.config.js` ```javascript const { sentryWebpackPlugin } = require("@sentry/webpack-plugin"); module.exports = { // ... other config above ... devtool: "hidden-source-map", // Source map generation must be turned on ("hidden-source-map", "source-map", etc.) plugins: [ sentryWebpackPlugin({ org: "___ORG_SLUG___", project: "___PROJECT_SLUG___", // Auth tokens can be obtained from your User Settings // and need `project:releases` and `org:read` scopes authToken: process.env.SENTRY_AUTH_TOKEN, sourcemaps: { // As you're enabling client source maps, you probably want to delete them after they're uploaded to Sentry. // Set the appropriate glob pattern for your output folder - some glob examples below: filesToDeleteAfterUpload: [ "./**/*.map", ".*/**/public/**/*.map", "./dist/**/client/**/*.map", ], }, release: { uploadLegacySourcemaps: { paths: ["."], ignore: ["./node_modules"], }, }, }), ], }; ``` The Sentry bundler plugins will automatically inject a release value into the SDK so you must either omit the `release` option from `Sentry.init` or make sure `Sentry.init`'s `release` option matches the plugin's `release.name` option exactly: ```javascript Sentry.init({ dsn: "___PUBLIC_DSN___", // When using one of the plugins, either remove the `release`` property here entirely or // make sure that the plugin's `release.name` option and the Sentry.init()'s release // option match exactly. // release: "my-example-release-1" }); ``` ## [Troubleshooting](https://docs.sentry.io/platforms/javascript/guides/react-router/sourcemaps/troubleshooting_js/legacy-uploading-methods.md#troubleshooting) If you followed all of the steps above but still have issues setting up source maps using the legacy method this section will try to help troubleshoot your setup. ### [Verify a release is configured in your SDK](https://docs.sentry.io/platforms/javascript/guides/react-router/sourcemaps/troubleshooting_js/legacy-uploading-methods.md#verify-a-release-is-configured-in-your-sdk) For uploaded source maps to be located and applied, the release needs to be created by the CLI or API (and the correct artifacts uploaded with it), and the name of that newly-created release needs to be specified in your SDK configuration. To verify this, open up the issue from the Sentry UI and check if the release is configured. If it says "*not configured*" or "*N/A*" next to **Release** on the right hand side of the screen (or if you do not see a `release` tag in the list of tags), you'll need to go back and [tag your errors](https://docs.sentry.io/platforms/javascript/guides/react-router/configuration/releases.md). If this is properly set up you'll see "Release: my\_example\_release". ### [Verify artifacts are uploaded](https://docs.sentry.io/platforms/javascript/guides/react-router/sourcemaps/troubleshooting_js/legacy-uploading-methods.md#verify-artifacts-are-uploaded) Once your release is properly configured and issues are tagged, you can find the artifacts uploaded to Sentry by navigating to **\[Settings] > Projects > Select your project > Source Maps**. Additionally, make sure all of the necessary files are available. For Sentry to de-minify your stack traces you must provide both the minified files (for example, app.min.js) and the corresponding source maps. In case the source map files do not contain your original source code (`sourcesContent`), you must additionally provide the original source files. Alternatively, sentry-cli will automatically embed the sources (if missing) into your source maps. ### [Verify `sourceMappingURL` is present](https://docs.sentry.io/platforms/javascript/guides/react-router/sourcemaps/troubleshooting_js/legacy-uploading-methods.md#verify-sourcemappingurl-is-present) Some CDNs automatically strip comments from static files, including JavaScript files. This can have the effect of stripping your JavaScript file of its `sourceMappingURL` directive, because it is considered a comment. For example, CloudFlare has a feature called [Auto-Minify](https://blog.cloudflare.com/an-all-new-and-improved-autominify/) which will strip `sourceMappingURL` if it is enabled. Double-check that your deployed, final JavaScript files have `sourceMappingURL` present. ### [Verify artifact distribution value matches value configured in your SDK](https://docs.sentry.io/platforms/javascript/guides/react-router/sourcemaps/troubleshooting_js/legacy-uploading-methods.md#verify-artifact-distribution-value-matches-value-configured-in-your-sdk) Whenever you are using a distribution identifier (the `dist` configuration option in the SDK), the same value has to be used during source map upload. Conversely, if your source maps are getting uploaded with a `dist` value, the same value must be set in your SDK. To add a `dist` value to your uploaded source maps, use the `--dist` flag with `sentry-cli` or the `dist` option in our [Sentry Bundler Plugins](https://github.com/getsentry/sentry-javascript-bundler-plugins) (like for example `@sentry/webpack-plugin`). To set the `dist` value in the SDK, use the `dist` option in your `Sentry.init()`. To verify that the distribution has been set correctly in the SDK, open an issue in the Sentry UI and check that the `dist` tag is present. For artifacts, go to the `Source Maps` page in project settings, choose the release shown on the event you just checked, and verify that the `dist` value (in the small oval next to the upload time) matches that on the event. ### [Verify artifact names match stack trace frames](https://docs.sentry.io/platforms/javascript/guides/react-router/sourcemaps/troubleshooting_js/legacy-uploading-methods.md#verify-artifact-names-match-stack-trace-frames) If you've uploaded source maps and they aren't applying to your code in an issue in Sentry, take a look at the JSON of the event and look for the `abs_path` to see exactly where we're attempting to resolve the file - for example, `http://localhost:8000/scripts/script.js` (`abs_path` will appear once for each frame in the stack trace - match this up with the file(s) that are not deminified.). A link to the JSON view can be found at the top of the issue page next to the date the event occurred. The uploaded artifact names must match these values. If you have **dynamic values in your path** (for example, `https://www.site.com/{some_value}/scripts/script.js`), you may want to use the [`rewriteFrames` integration](https://docs.sentry.io/platforms/javascript/guides/react-router/configuration/integrations/rewriteframes.md) to change your `abs_path` values. #### [Using sentry-cli](https://docs.sentry.io/platforms/javascript/guides/react-router/sourcemaps/troubleshooting_js/legacy-uploading-methods.md#using-sentry-cli) If your `sourceMappingURL` comment is similar to: ```javascript // -- end script.min.js (located at http://localhost:8000/scripts/script.min.js) //# sourceMappingURL=script.min.js.map ``` An example `sentry-cli` command to upload these files correctly would look like this (assuming you're in the `/scripts` directory, running your web server from one directory higher, which is why we're using the `--url-prefix` option): ```shell sentry-cli sourcemaps upload --url-prefix '~/scripts' . ``` This command uploads all JavaScript files in the current directory. The Artifacts page in Sentry should now look like: ```bash ~/scripts/script.js ~/scripts/script.min.js ~/scripts/script.min.js.map ``` Alternately you can specify which files to upload. For example: ```bash sentry-cli sourcemaps upload --url-prefix '~/scripts' script.min.js script.min.js.map ``` You can also upload it with the fully qualified URL. For example: ```bash sentry-cli sourcemaps upload --url-prefix 'http://localhost:8000/scripts' . ``` #### [Using the API](https://docs.sentry.io/platforms/javascript/guides/react-router/sourcemaps/troubleshooting_js/legacy-uploading-methods.md#using-the-api) You can alternately [use our API](https://docs.sentry.io/api/releases/update-an-organization-release-file.md) to upload artifacts, following the same naming convention explained here. ```shell curl -X POST \ https://sentry.io/api/0/organizations/ORG_SLUG/releases/VERSION/files/ \ -H 'Authorization: Bearer AUTH_TOKEN' \ -H 'content-type: multipart/form-data' \ -F file=@script.min.js.map \ -F 'name=~/scripts/script.min.js.map' ``` #### [Using the `~`](https://docs.sentry.io/platforms/javascript/guides/react-router/sourcemaps/troubleshooting_js/legacy-uploading-methods.md#using-the-) The `~` is used in Sentry to replace the scheme and domain. It is not a glob! `http://example.com/dist/js/script.js` will match `~/dist/js/script.js` or `http://example.com/dist/js/script.js` but will NOT match `~/script.js`. ### [Multiple Origins](https://docs.sentry.io/platforms/javascript/guides/react-router/sourcemaps/troubleshooting_js/legacy-uploading-methods.md#multiple-origins) It's not uncommon for a web application to be accessible at multiple origins. For example: * Website is operable over both `https` and `http` * Geolocated web addresses: such as `https://us.example.com`, `https://eu.example.com` * Multiple static CDNs: such as `https://static1.example.com`, `https://static2.example.com` * Customer-specific domains/subdomains In this situation, **identical** JavaScript and source map files may be located at two or more distinct origins. In this situation we recommend using our special tilde (`~`) prefix on paths. So for example, if you have the following: * * You can upload using the URL of `~/js/app.js`. This will tell Sentry to ignore the domain and use the artifact for any origin. Additionally you can also upload the same file under multiple names. Under the hood Sentry will deduplicate these. The \~ prefix tells Sentry that for a given URL, **any** combination of protocol and hostname whose path is `/js/app.js` should use this artifact. Use this method **only** if your source/source map files are identical at all possible protocol/hostname combinations. **Sentry will prioritize full URLs over tilde prefixed paths**, if found. ### [Verify artifact names match `sourceMappingURL` value](https://docs.sentry.io/platforms/javascript/guides/react-router/sourcemaps/troubleshooting_js/legacy-uploading-methods.md#verify-artifact-names-match-sourcemappingurl-value) The `sourceMappingURL` comment on the last line of your bundled or minified JavaScript file tells Sentry (or the browser) where to locate the corresponding source map. This can either be a fully qualified URL, a relative path, or the filename itself. When uploading artifacts to Sentry, you must name your source map files with the value the file resolves to. That is, if your file is similar to: ```javascript // -- end script.min.js //# sourceMappingURL=script.min.js.map ``` and is hosted at , then Sentry will look for that source map file at . Your uploaded artifact must therefore be named `http://example.com/js/script.min.js.map` (or `~/js/script.min.js.map`). Or, if your file is similar to: ```javascript //-- end script.min.js //# sourceMappingURL=https://example.com/dist/js/script.min.js.map ``` then your uploaded artifact should also be named `https://example.com/dist/js/script.min.js.map` (or `~/dist/js/script.min.js.map`). Finally, if your file is similar to: ```javascript //-- end script.min.js //# sourceMappingURL=../maps/script.min.js.map ``` then your uploaded artifact should be named `https://example.com/dist/maps/script.min.js.map` (or `~/dist/maps/script.min.js.map`). ### [Verify Artifacts Are Uploaded Before Errors Occur](https://docs.sentry.io/platforms/javascript/guides/react-router/sourcemaps/troubleshooting_js/legacy-uploading-methods.md#verify-artifacts-are-uploaded-before-errors-occur) Sentry expects that source code and source maps in a given release are uploaded to Sentry **before** errors occur in that release. If you upload artifacts **after** an error is captured by Sentry, Sentry will not go back and retroactively apply any source annotations to those errors. Only new errors triggered after the artifact was uploaded will be affected. ### [Verify your source maps are built correctly](https://docs.sentry.io/platforms/javascript/guides/react-router/sourcemaps/troubleshooting_js/legacy-uploading-methods.md#verify-your-source-maps-are-built-correctly) We maintain an online validation tool that can be used to test your source maps against your **hosted** source: [sourcemaps.io](https://sourcemaps.io). Alternatively, if you are using Sentry CLI to upload source maps to Sentry, you can use the `--validate` command line option to verify your source maps are correct. ### [Verify your source maps work locally](https://docs.sentry.io/platforms/javascript/guides/react-router/sourcemaps/troubleshooting_js/legacy-uploading-methods.md#verify-your-source-maps-work-locally) If you find that Sentry is not mapping filename, line, or column mappings correctly, you should verify that your source maps are functioning locally. To do so, you can use Node.js coupled with Mozilla's [source-map library](https://github.com/mozilla/source-map). First, install `source-map` globally as an npm module: ```bash npm install -g source-map ``` Then, write a Node.js script that reads your source map file and tests a mapping. Here's an example: ```javascript var fs = require("fs"), path = require("path"), sourceMap = require("source-map"); // Path to file that is generated by your build tool (webpack, tsc, ...) var GENERATED_FILE = path.join(".", "app.min.js.map"); // Line and column located in your generated file (for example, the source // of the error from your minified file) var GENERATED_LINE_AND_COLUMN = { line: 1, column: 1000 }; var rawSourceMap = fs.readFileSync(GENERATED_FILE).toString(); new sourceMap.SourceMapConsumer(rawSourceMap).then(function (smc) { var pos = smc.originalPositionFor(GENERATED_LINE_AND_COLUMN); // You should see something like: // { source: 'original.js', line: 57, column: 9, name: 'myfunc' } console.log(pos); }); ``` If you have the same (incorrect) results locally as you do via Sentry, double-check your source map generation configuration. ### [Verify artifacts are not gzipped](https://docs.sentry.io/platforms/javascript/guides/react-router/sourcemaps/troubleshooting_js/legacy-uploading-methods.md#verify-artifacts-are-not-gzipped) The Sentry API currently only works with source maps and source files that are uploaded as plain text (UTF-8 encoded). If the files are uploaded in a compressed format (for example, gzip), they will be not be interpreted correctly. If you are using `sentry-cli` to upload your artifacts, starting with version `2.4.0` you can add the `--decompress` flag to your `sourcemaps upload` commands. Sometimes build scripts and plugins produce pre-compressed minified files (for example, webpack's [compression plugin](https://github.com/webpack/compression-webpack-plugin)). In these cases, you'll need to disable such plugins and perform the compression **after** the generated source maps/source files have been uploaded to Sentry. ### [(Self-Hosted Sentry) Verify the `symbolicator` service is operating normally](https://docs.sentry.io/platforms/javascript/guides/react-router/sourcemaps/troubleshooting_js/legacy-uploading-methods.md#self-hosted-sentry-verify-the-symbolicator-service-is-operating-normally) If you're running a self-hosted version of Sentry, you can verify that the `symbolicator` service/container is operating normally by checking the container's logs. ### [(Self-Hosted Sentry via Docker) Verify workers are sharing the same volume as web](https://docs.sentry.io/platforms/javascript/guides/react-router/sourcemaps/troubleshooting_js/legacy-uploading-methods.md#self-hosted-sentry-via-docker-verify-workers-are-sharing-the-same-volume-as-web) Sentry does source map calculation in its workers. This means the workers need access to the files uploaded through the front end. Double check that the cron workers and web workers can read/write files from the same disk. ### [Verify you are not using the `source-map-support` package](https://docs.sentry.io/platforms/javascript/guides/react-router/sourcemaps/troubleshooting_js/legacy-uploading-methods.md#verify-you-are-not-using-the-source-map-support-package) The Sentry Node.js SDK generally works well with the [source-map-support](https://www.npmjs.com/package/source-map-support) package if you don't already have source maps uploaded to Sentry. If you are uploading source maps to Sentry or if you are using a Sentry SDK in the browser, your code cannot use the `source-map-support` package. `source-map-support` overwrites the captured stack trace in a way that prevents our source map processors from correctly parsing it.