How do I fix a CORS issue for Heatmaps and Session Recordings

When Matomo records a heatmap or session, it saves the HTML of your page along with its CSS (Cascading Style Sheets). This ensures that heatmaps and session recordings still display correctly even if your site’s CSS changes later. To achieve this, Matomo will first try to read the CSS directly from the DOM. If that fails, it will attempt to fetch the CSS with an additional HTTP request.

In most cases this works automatically, but if your CSS is loaded from another domain, e.g. through a CDN (Content Delivery Network), then additional configuration may be required. If you notice styling issues in heatmaps or session recordings, such as missing fonts or layout changes, one possible cause is that CORS (Cross-Origin Resource Sharing) is blocking access to your CSS.

This guide explains how diagnose the issue and configure your CORS settings if needed.

Check if CORS is blocking requests

Styling problems in heatmaps and session recordings can happen for different reasons. A common one is when CORS blocks access to your CSS.

  1. Open your browser’s developer tools (usually with F12) and look in the Console or Network tab while viewing a heatmap or session recording.
  2. If you see a CORS policy error, then it is preventing Matomo from loading your CSS. For example:
Access to XMLHttpRequest at 'https://example/style.css' from origin 'https://my-site.com' has been blocked by CORS policy: No 'Access-Control-Allow-Origin' header is present on the requested resource.

If you do not see a CORS error, the styling problem is likely caused by another issue. Explore the troubleshooting FAQs for further guidance.

How to fix a CORS issue

When CORS blocks Matomo from loading your CSS, you need to update your settings. This ensures Matomo can read the CSS from the specified site.

  1. Add the crossorigin=”anonymous” attribute to your CSS link tags. This allows Matomo to access CSS content more efficiently without an extra HTTP request.
    <link rel="stylesheet" href="{PATH_TO_YOUR_CSS_FILE}" crossorigin="anonymous">
  2. Configure your web server to return the Access-Control-Allow-Origin header for CSS files. This lets Matomo load CSS from a different domain.
  3. If Matomo runs at https://matomo.example.com and your CSS is hosted on https://www.example.com or served through a CDN, configure the server (that delivers the stylesheet) to return the following header:
    Access-Control-Allow-Origin: https://www.example.com
  4. Note: It is recommended to limit the header to CSS and font files. Applying CORS headers globally to all resources can introduce security risks. If you are unsure of how to set the CORS headers, contact your system administrator or web hosting provider.
  5. Check you have added the crossorigin="anonymous" to your stylesheet link.
  6. If your site or CDN caches CSS, clear it so the updated headers are applied.
  7. Always verify your changes by looking for CORS errors in the browser’s dev tools > Console or Network tab.

Reviewing these points can help ensure heatmaps and session recordings display with the correct styling. However, if the problem persists, refer to the troubleshooting guide on styling issues.

Previous FAQ: How do I apply custom stylesheets when a heatmap is generated or a session recording replayed?