Troubleshoot Heatmaps

"Heatmaps isn't available for your organization"

This message appears for legacy organizations, which Amplitude created before its current packaging. Legacy organizations require manual enablement and a few considerations:

• Heatmaps sends heatmap events directly to your project, so the events appear in your event taxonomy. Blocking any heatmap event type or property can stop Heatmaps from working, and these events can appear in "Any Event" queries, especially in group-bys.
• If your organization uses CDP integrations, Amplitude can forward heatmap events to your data warehouse.
• Heatmaps sends new event properties. If your organization is at its property limit, raise the limit before Heatmaps can work.

A heatmap is blank or shows "No heatmap available"

A blank heatmap usually means the data is brand new, the URL filter doesn't match, or your instrumentation doesn't meet the requirements. Work through these checks:

• Wait for processing. Right after you install or enable Session Replay, the URL list and overlays can be empty until Amplitude processes replay and click data. This can take a few minutes.
• Check the URL filter. Confirm that your URL match option matches URLs in your Amplitude events. A pattern that's too narrow returns no data.
• Confirm SDK versions. Heatmaps requires the Session Replay Browser SDK Plugin 1.7.0 or later, or the Session Replay Standalone SDK 1.14.0 or later. Verify that the live deployed site serves the updated SDK, not only that the version changed in your code.
• Confirm the data thresholds. Heatmaps appear after Amplitude collects enough data: at least 10 separate pages, with about 500 tracked replay clicks on each page.
• Restore the page URL property. If the [Amplitude] Page URL property is missing, Heatmaps can't match URLs. Restore it in Data > Properties: search for [Amplitude] Page URL and click Restore.

The background doesn't show the right page state

A heatmap background is a snapshot of a Session Replay, so the default snapshot might capture an unwanted state, such as a page with an open modal that covers the content. Use the Choose Background option to move through the available snapshots and select a state that matches the page you want to analyze. Each heatmap fetches eight backgrounds from the states that generated the most actions.

Backgrounds aren't a pixel-perfect copy of the live page. Pages that rely on a content security policy (CSP) that blocks external resources, or that use Shadow DOM styling, can render differently in the background.

A mobile heatmap shows no data

Heatmaps supports web-based session replays only and doesn't support mobile apps or SDKs. If a mobile web heatmap shows no data even though mobile replays exist, confirm that the device type you selected for the heatmap matches the viewport you captured. A mismatch between the selected device type and the captured screenshot can produce warnings, poor rendering, or no usable background.

Clicks merge on single-page apps

Heatmaps compute data per URL string, not per view. On a single-page app (SPA) where many states share one URL, a heatmap merges the clicks from all of those states into one overlay. To separate the states, create individual heatmaps with narrower URL filters that target each state, or adjust your URL structure so each view has a distinct URL.

Heatmaps look incomplete when you use sampling

Heatmaps appear that you didn't create

Amplitude automatically creates a small set of heatmaps for your highest-traffic pages after your data meets the thresholds. This automatic creation runs one time and selects the pages with the most tracked clicks. You can safely delete these heatmaps, and Amplitude doesn't recreate them.

A banner asks you to update your SDK