Troubleshooting

There are a few cases where the replay playback won't match the look of your application. Below, are some common causes and solutions if you experience this.

Missing elements from the replay

• You may be using unsupported and/or deprecated elements such as <frame> (not to be confused with <iframe>).
• The element may be blocked by the privacy configuration (by default, elements with the class name sentry-block or the attribute data-sentry-block).

CSS is wrong or missing

• There may be edge cases with complex CSS selectors which break the styling. Please file an issue on GitHub if you encounter this.

Canvas is supported in SDK versions >= 7.98.0. Please see the canvas setup documention to get started with canvas recordings.

If you are on a supported SDK version and your canvas elements still aren't getting captured, check if you have images or videos loaded from foreign origins inside your canvas. Any data loaded from an origin without CORS approval is not considered secure and will throw a SecurityError when trying to use the replay canvas integration. To fix this issue, set crossorigin="anonymous" to your images or videos. This will allow images that are loaded from foreign origins to be used in canvas as if they have been loaded from the current origin. See the CORS documention for more information about cross-origin access.

The integration needs to enable preserveDrawingBuffer to export images from 3D and WebGL canvases. This can negatively affect canvas performance. If your canvas application is impacted by enabling preserveDrawingBuffer, you'll need to enable manual snapshotting and call a snapshot() method inside of your re-paint loop.

The replay 'video' is actually a video-like reproduction of the HTML on your website. This means that all the external resources your site uses (CSS/Images/Fonts), will be rendered by the corresponding <style>, <img> and <video> tags on your site. Add sentry.io to your CORS policy so the iframe hosted on sentry.io can fetch and display these resources.

Note that only static, publicly hosted videos (for example, src="./my-video.mp4") can be captured by Replay. Streamed videos and similar are not supported.

There might be fewer rage clicks than you expect if the user stopped waiting for the site to respond before the 7 second threshold. This is why the rage click issues that you do see are so valuable, because the user that clicked at least 3 times and continued waiting at least 7 seconds for the site to respond is likely very frustrated.

You might also see more rage clicks than you expected from buttons that don't trigger a DOM mutation or page scroll (such as "Print" and "Download" buttons). There is no reliable way for the SDK to detect that a download or print has initiated, so a slow click might be generated even if the button is not actually "dead". For these cases, you can configure the SDK via slowClickIgnoreSelectors - see Configuration for more details.

For example, to ignore detection of dead and rage clicks for download links in your application:

Sentry.replayIntegration({
  slowClickIgnoreSelectors: [
    ".download",
    // Any link with a label including "download" (case-insensitive)
    'a[label*="download" i]',
  ],
});

By default, Replay will capture basic information about all outgoing fetch and XHR requests in your application. This includes the URL, request and response body size, method, and status code. The intention is to limit the chance of collecting private data. You can configure the SDK to capture bodies and additional headers.

Another reason you might not see the body is if the format is not supported. We only capture text-based bodies, including JSON, XML, FormData, and similar data types. Any captured body will be truncated to 150k characters. When we identify the body as JSON, we will try to truncate it while keeping the payload valid JSON. Bodies of byte, file, or media types are not captured.

More details about this feature can be found in the configuration page.

If you're experiencing slowdowns on your website, first make sure you're on the latest version of our SDK, which will have the most up-to-date bug fixes and performance improvements.

We've identified two major potential reasons for impacted performance and have added several performance degradation safeguards as a result. The two culprits are websites that have a large numbers of mutations (Read the entry below to learn more.) and large console messages.

To mitigate these problems, SDK version 7.54.0 will truncate console messages and disable Replay recordings on pages that have a large number of mutations.

If you're having any problems with the latest SDK version, we want to hear about it. Please open a GitHub issue and describe your situation.

Because of the complexity of the browser environment, there's a significant amount of code necessary in order for Session Replay to work. And while enabling Session Replay will add about 50 kb (gzipped) to your application bundle, we believe the benefits will outweigh the cost.

We're always working on ways to reduce the bundle size. Additionally, there are steps you can take in order to reduce the size of Session Replay based on your specific use case. See Tree Shaking for more information.

The Sentry SDK attempts to minimize potential performance overhead in a few different ways. For example, by keeping track of the number of DOM mutations that are happening then disabling recording when a large number of changes are detected. Many simultaneous mutations can slow down a web page whether Session Replay is installed or not, but when a large number of mutations happen, the Replay client can incur an additional slowdown because it records each change.

If you're seeing the "A large number of mutations was detected" message while watching a replay, it means that your page could be optimized. For example, a dropdown list with thousands of entries could be refactored so that rows are virtualized where only the visible rows are rendered in the DOM. Another potential solution is to paginate the results fetch more data as the user scrolls through it. The SDK has a configuration that allows you to configure the limits before recording stops.

Our masking logic doesn't run on iframe content that's provided using the srcdoc attribute, rather than loaded in via src.

To hide this content, block the iframe, as described in our Session Replay Privacy docs.

This is not a supported use-case. The replay package is built to work on a website and not as an externally-loaded script via browser extension or other mechanism. In fact, Sentry's Session Replay product can help developers find out when a third-party Chrome extension causes otherwise hard to debug or reproduce issues with their website.

Apollo Client sends an abort signal via AbortController whenever a query completes, to clean up and cancel all in-flight queries. When this happens, the Replay can't capture the response body because the request is handled as aborted before Replay can access the response.

To avoid this, disable this behavior of Apollo Client by configuring your own abort signal:

const abortController = new AbortController();

const httpLink = createHttpLink({
  // ... other options
  fetchOptions: {
    signal: abortController.signal, // overwrite the default abort signal
  },
});

With this configuration, Replay is able to capture response bodies from Apollo Client requests.

Using the captureConsoleIntegration can cause replays to record as if you have triggered an exception. You can use beforeErrorSampling to avoid this behavior.

There are certain cases (such as clicking a button to play an audio clip) where Sentry incorrectly records a click as a dead click (note: rage clicks are a subset of dead clicks). As a workaround, you can use the slowClickIgnoreSelector configuration option to ignore dead clicks for specific selectors.

If you want to turn off rage click issues altogether, you can disable them by going to the Settings page in Sentry, clicking "Projects", and selecting the project for which you want to disable rage clicks. From here, select "Replays" under the "PROCESSING" heading and toggle off "Create Rage Click Issues".

Clicks in replays can appear in the incorrect location due to rendering differences between your application and the replayer. A common case of this is with text rendering: if custom fonts are not loaded properly in the replayer, it can cause the height of elements to differ between production and the replay. This means that the scroll position will be incorrect and will result in mouse clicks appearing in the wrong location. If you are hosting your own fonts, please configure the Access-Control-Allow-Origin headers to allow the sentry.io host to load your fonts, otherwise the replayer will be unable to load them due to CORS.

Text masking of variable-width fonts can also cause this because the size of the masking text ("*") will not necessarily have the same dimensions as the original character it replaced. There is currently no workaround; please follow this GitHub Issue for updates.