When Matomo captures a heatmap or session recording, it saves the HTML structure of your page so the layout can be reproduced later. The CSS and images, however, are not stored by Matomo. They are still loaded directly from your website when you view the heatmap or replay the recording.

If your heatmap or session recording does not appear styled correctly, there could be several reasons. This troubleshooting guide covers the most common issues and how to resolve them.

Removed or missing CSS files

If CSS or image files that were part of the original page are later removed from your website, the heatmap or session replay may no longer display correctly. The tracking data itself is still accurate, and only the visual appearance is affected.

  1. To fix this, restore the missing CSS or image files on your website.
  2. If the files are present but the screenshot still doesn’t render correctly, regenerate the screenshot by deleting the existing heatmap screenshot in Matomo. It will then create a new screenshot with the available CSS.
  3. You can manually force this by appending ?pk_hsr_forcesample=1 to the page URL.
  4. In some cases, the issue may be related to how Matomo loads CSS. By default, Matomo can load CSS from the database.

CORS errors

If your CSS is served from another domain, e.g. a CDN (Content Delivery Network), Matomo may not be able to load it correctly due to cross-origin restrictions. This will require configuring the CORS headers on the CSS files. Read more about fixing CORS issues.

Note: When loading a cached CSS version with unique file names (e.g style.223ks2j3.css) from another domain and cannot adjust the CORS settings, you can add a data-matomo-href attribute on the web page to point to an uncached CSS file. In this example, Matomo will load style.css when displaying the heatmap:

<link href="style.223ks2j3.css" data-matomo-href="style.css">

HTTPS support

If your website does not fully support HTTPS, heatmaps or session recordings may not load correctly in Matomo. Enable HTTPS on your website and access Matomo using https:// to ensure a secure connection.

Note: The URL configuration for heatmaps defines how Matomo matches URLs:

  • Equals simple ignores protocol, URL parameters, and trailing slashes.
  • Equals exactly requires an exact match, including protocol, parameters, and trailing slashes.

Browser extensions

Privacy tools or ad blockers (such as Privacy Badger) can sometimes block website resources, which may result in unstyled recordings. Disable the extension for your Matomo domain and refresh the page to check if styling is restored.

Still not working?

If your heatmap or session recording is still not styled after trying these solutions, explore the [troubleshooting FAQs] for other solutions. If the issue persists, contact Matomo Support for further assistance.

Previous FAQ: Matomo is not recording any Heatmaps or Sessions, what can I do?