You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Source maps can sometimes be tricky to get going. If you're having trouble, you can try using our verification tool inside `sentry-cli`, or go through the steps listed below yourself. Please keep in mind, that the `sentry-cli` is a work-in-progress, and we're actively working to improve it.
2
-
3
-
To use the automated verification process, [install and configure](/product/cli/)`sentry-cli`. Once completed, use the `sourcemaps explain` command, by calling it with the event ID that can be found at the top of the **Issue Details** page in [sentry.io](https://sentry.io). For example, "Event fdfd1337e3964cd6a4d11f35357a4c43 | JSON (42.0 KiB)".
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.
17
-
18
-
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](../../configuration/releases/). If this is properly set up you'll see "Release: my_example_release".
19
-
20
-
</PlatformSection>
21
-
22
-
## Verify artifacts are uploaded
23
-
24
-
Once your release is properly configured and issues are tagged, you can find the artifacts uploaded to Sentry by navigating to **[Project] » Project Settings » Source Maps**.
25
-
26
-
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.
27
-
28
-
## Verify `sourceMappingURL` is present
29
-
30
-
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.
31
-
32
-
Double-check that your deployed, final JavaScript files have `sourceMappingURL` present.
33
-
34
-
Alternately, instead of `sourceMappingURL`, you can set a `SourceMap` HTTP header on your minified file. If this header is present, Sentry will use it to discover the location of your source map.
## Verify artifact distribution value matches value configured in your SDK
39
-
40
-
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.
41
-
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()`.
42
-
43
-
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.
44
-
45
-
</PlatformSection>
46
-
47
-
## Verify artifact names match stack trace frames
48
-
49
-
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.
50
-
51
-
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 <PlatformSectionnotSupported={["node"]}><PlatformLinkto="/configuration/integrations/plugin/#rewriteframes">`rewriteFrames` integration</PlatformLink></PlatformSection><PlatformSectionsupported={["node"]}><PlatformLinkto="/configuration/integrations/pluggable-integrations/#rewriteframes">`rewriteFrames` integration</PlatformLink></PlatformSection> to change your `abs_path` values.
52
-
53
-
### Using sentry-cli
54
-
55
-
If your `sourceMappingURL` comment is similar to:
56
-
57
-
```javascript
58
-
// -- end script.min.js (located at http://localhost:8000/scripts/script.min.js)
59
-
//# sourceMappingURL=script.min.js.map
60
-
```
1
+
<Note>
61
2
62
-
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):
3
+
If you previously set up source maps, we suggest updating your tools (SDK, bundler plugins, Sentry CLI).
63
4
64
-
```shell
65
-
sentry-cli releases files VERSION upload-sourcemaps . --url-prefix '~/scripts'
66
-
```
5
+
It is generally easier to upgrade to the latest versions and follow the current process rather than troubleshooting with older versions.
67
6
68
-
This command uploads all JavaScript files in the current directory. The Artifacts page in Sentry should now look like:
7
+
For information on the legacy method of uploading source maps, please see the guide on <PlatformLinkto="/sourcemaps/troubleshooting_js/uploading-without-debug-ids">Uploading without Debug IDs</PlatformLink>.
69
8
70
-
```
71
-
~/scripts/script.js
72
-
~/scripts/script.min.js
73
-
~/scripts/script.min.js.map
74
-
```
9
+
</Note>
75
10
76
-
Alternately you can specify which files to upload. For example:
11
+
Setting up source maps can be tricky, but it's worth it to get it right. To troubleshoot your source maps set up, you can either:
77
12
78
-
```
79
-
sentry-cli releases files VERSION upload-sourcemaps script.min.js script.min.js.map --url-prefix '~/scripts'
80
-
```
13
+
1. Use our automated verification tool inside `sentry-cli`, or
14
+
2. Follow the manual steps listed below
81
15
82
-
You can also upload it with the fully qualified URL. For example:
16
+
## Use the CLI
83
17
84
-
```
85
-
sentry-cli releases files VERSION upload-sourcemaps . --url-prefix 'http://localhost:8000/scripts'
86
-
```
18
+
To use the automated verification process, install and configure the Sentry [Command Line Interface](/product/cli/). Then, use the `sourcemaps explain` command, calling it with the relevant event ID, found in the top-left corner of the **Issue Details** page in [sentry.io](https://sentry.io).
87
19
88
-
### Using the API
20
+
For example, "Event ID: c2ad049f":
89
21
90
-
You can alternately [use our API](/api/releases/update-an-organization-release-file/) to upload artifacts, following the same naming convention explained here.
22
+
The `~` is used in Sentry to replace the scheme and domain. It is not a glob!
104
-
105
-
`http://example.com/dist/js/script.js` will match `~/dist/js/script.js` or `http://example.com/dist/js/script.js`
106
-
107
-
but will NOT match `~/script.js`.
28
+
The CLI output should give you useful information about what went wrong with your source maps setup.
29
+
If it doesn't, let us know by filing an issue on our [Sentry CLI repo](https://github.com/getsentry/sentry-cli) so we can make it better.
108
30
109
-
## Multiple Origins
31
+
## Follow Manual Steps
110
32
111
-
It's not uncommon for a web application to be accessible at multiple origins. For example:
33
+
### Verify Artifacts Are Uploaded
112
34
113
-
- Website is operable over both `https` and `http`
114
-
- Geolocated web addresses: such as `https://us.example.com`, `https://eu.example.com`
115
-
- Multiple static CDNs: such as `https://static1.example.com`, `https://static2.example.com`
116
-
- Customer-specific domains/subdomains
35
+
Verify your artifacts are being uploaded to Sentry. You can find them at **[Settings] > Projects > Select your project > Source Maps**.
36
+
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.
117
37
118
-
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.
38
+
## Verify You Are Building Source Maps
119
39
120
-
So for example, if you have the following:
40
+
Bundlers and tools (like `tsc`) that generate code, often require you to manually set specific options to generate source maps.
121
41
122
-
-https://static1.example.com/js/app.js
123
-
-https://static2.example.com/js/app.js
42
+
If you followed one of our tool-specific guides, verify you configured your tool to emit source maps and that the source maps contain your original source code in the `sourcesContent` field.
124
43
125
-
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.
44
+
## Verify Your Source Files Contain Debug ID Injection Snippets
126
45
127
-
Additionally you can also upload the same file under multiple names. Under the hood Sentry will deduplicate these.
46
+
In the JavaScript files you uploaded to Sentry, search for code that roughly looks like `e._sentryDebugIds=e._sentryDebugIds||{}`. This code snippet might look different depending on how you process your code.
128
47
129
-
<Note>
130
-
131
-
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.
132
-
133
-
</Note>
134
-
135
-
## Verify artifact names match `sourceMappingURL` value
136
-
137
-
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.
138
-
139
-
That is, if your file is similar to:
48
+
If this code exists in a bundle, that bundle will be able to be matched to a source file. Every bundle you deploy in your app needs to have this snippet in order to be correctly source mapped.
140
49
141
-
```javascript
142
-
// -- end script.min.js
143
-
//# sourceMappingURL=script.min.js.map
144
-
```
50
+
If your source code does not contain this snippet and you're using a Sentry plugin for your bundler, please check that you are using the latest version and please verify that the plugin is correctly processing your files. Set the `debug` option to `true` to print useful degbugging information.
145
51
146
-
and is hosted at http://example.com/js/script.min.js, then Sentry will look for that source map file at http://example.com/js/script.min.js.map. Your uploaded artifact must therefore be named `http://example.com/js/script.min.js.map` (or `~/js/script.min.js.map`).
52
+
If you're using the Sentry CLI, verify that you're running the `inject` command **before** you upload to Sentry and **before** you deploy your files.
147
53
148
-
Or, if your file is similar to:
54
+
## Verify Your Source Files Contain Debug ID Injection Snippets
When inspecting the event payload JSON data in Sentry, verify that the events have a `debug_meta` property. If this property is missing and you already made sure your source files contain debug ID injection snippets, this likely means that you're using an outdated SDK.
154
57
155
-
then your uploaded artifact should also be named `https://example.com/dist/js/script.min.js.map` (or `~/dist/js/script.min.js.map`).
58
+
We generally recommend upgrading to the latest version, and for source maps to work you need to at least use version `7.47.0`.
156
59
157
-
Finally, if your file is similar to:
158
-
159
-
```javascript
160
-
//-- end script.min.js
161
-
//# sourceMappingURL=../maps/script.min.js.map
162
-
```
60
+
After you verified your event has a `debug_meta` property, the next thing to check is whether all frames inside the `raw_stacktrace` property inside the events have an `abs_path` property that exactly matches one of the `code_file` properties inside the `debug_meta` images.
163
61
164
-
then your uploaded artifact should be named `https://example.com/dist/maps/script.min.js.map` (or `~/dist/maps/script.min.js.map`).
62
+
If a stack frame doesn't match an entry inside `debug_meta`, make sure that the relevant file contains a debug ID injection snippet.
165
63
166
-
## Verify artifacts are uploaded before errors occur
64
+
## Verify Artifacts Are Uploaded Before Errors Occur
167
65
168
66
Sentry expects that source code and source maps in a given release are uploaded to Sentry **before** errors occur in that release.
169
67
@@ -185,7 +83,7 @@ First, install `source-map` globally as an npm module:
185
83
npm install -g source-map
186
84
```
187
85
188
-
Then, write a script that reads your source map file and tests a mapping. Here's an example:
86
+
Then, write a Node.js script that reads your source map file and tests a mapping. Here's an example:
![getsantry[bot]](https://avatars.githubusercontent.com/in/66573?v=4&size=40){kind=avatar}
0 commit comments