First, we recommend to open your Heatmap or Session Recording configuration in the Matomo (Piwik) UI to make sure you have configured a correct target page or entry page. There is a URL validator just next to the page configuration that lets you check if a heatmap or session would be recorded on a certain page URL. This way you can find typos and other configuration problems.

If you are using a Matomo Cloud Business plan there is no need to follow the troubleshooting steps below. Your heatmaps and session recording plugin is configured and ready to go. If you are facing issues with blank heatmaps or session recordings please check our guide here: Blank Heatmaps in Matomo

If your configuration is correct, its likely the request to $yourPiwikDomain/plugins/HeatmapSessionRecording/configs.php fails because of restrictions in your web server configuration, you can check for the request to configs.php in your browsers developer tools.

Please log in to your Matomo as a Super User and go to Administration => Diagnostic => System Check. There is a system check for Heatmap & Session Recording that checks whether the file is accessible from the internet / intranet or not. If not, you will see an error message explaining the problem.

If the system check says everything is ok but it still doesn’t work, you can also check manually if the file « configs.php » file is accessible. Open your website, right click and select « Inspect ». Now go to the network tab and reload your website. You should see an entry for « configs.php » with a status of « 200 OK ». If there is a status like « 403 », then you need to modify your web server to allow access to this file.

Please note: When manually checking if the configs.php is available from your browser you may see a « 400 Bad Request » response. This is the expected response when no parameters are sent and indicates that access to the configs.php file is not being blocked.

You should also verify whether the « matomo.js » file is writable, allowing the heatmap tracker code to be automatically inserted into your Matomo JavaScript tracking file.

If you are using Cloudflare or something similar, you may need to invalidate your cache for the Heatmap tracking code to appear in your « piwik.js » tracking file. You might also want to edit your « config/config.ini.php » file and add or modify the following two lines:

[HeatmapSessionRecording]
add_tracking_code_only_when_needed = 0

Still not working? Please get in touch with us, we are happy to help.