Troubleshoot Heatlens

1. No recorded pages
2. The quota increases but the map is empty
3. Missing or old snapshot
4. Incomplete reconstructed page
5. Points without tooltips or in the wrong place
6. A SPA counts too many pages or captures too early
7. PNG unavailable, reduced or different from JSON
8. Missing menu or rejected commands
9. Old interface after an update
10. Missing notifications, repetition or purge
11. Prepare a support request

Check ordinary Matomo tracking first, then the campaign and report filters. Use a synthetic page and preserve existing records while investigating.

No recorded pages

1. Check the correct Matomo site (idSite) and a native page view. Fix blocked Matomo tracking before investigating Heatlens.
2. Check that the plugin and its system tracking setting are enabled. Run the tracker diagnostic.
3. Check active status, an available quota, 100% sampling for the test, device and any country restriction. Test the URL in the form, including trailing slash, case, query parameters and combined conditions.
4. Grant the required consent on a test page and check Matomo opt-out. Cookie consent alone is insufficient.
5. A custom trigger must return exactly true synchronously. Allow the configuration to load.
6. In the browser Network panel, check matomo.js, index.php?module=Heatlens&action=trackingConfig and requests to the Matomo collector. A blocker, CSP, proxy or firewall may prevent them.

Expected result: available Heatlens configuration, then the campaign counter increases after consented interaction. A successful collector HTTP response does not guarantee a Heatlens write: native Matomo tracking continues if that write fails. Check Matomo/PHP server logs, particularly Heatlens collection failed. Do not globally disable CSP, consent or a firewall to work around the issue.

The quota increases but the map is empty

Select all retained dates, remove the segment and check the device and snapshot revision. Consider the Matomo site's timezone. The quota is cumulative; report pages depend on filters and retention.

Expected result: the report page count reflects the selection. Purging may leave a nonzero quota after detailed data expires. Changing filters or resuming a campaign does not reset its cap.

Missing or old snapshot

Check automatic/manual mode, reference URL and delay. A reference URL does not start a crawler: an eligible visit must load it. In manual mode call Heatlens.captureSnapshot after consent and collection have started.

This call never replaces an existing snapshot. Create a new revision, reload the page or send the next Matomo page view, then capture again. The new revision does not inherit previous interactions; old revisions remain readable. A true return means queued, not acknowledged by the server. See the capture guide.

Incomplete reconstructed page

Read the map warnings. Unreadable cross-origin CSS, variables, complex CSS constructs, protected media, iframes, video or content not loaded at capture time may be missing or replaced with blocks.

Wait for rendering, adjust the delay or manually capture a new revision. Check original width first; custom width needs responsive metadata. Heatlens retains permitted styles from accessible stylesheets, but reports do not load external stylesheets or scripts. Reconstruction is not pixel-perfect video recording.

Points without tooltips or in the wrong place

Click/movement tooltips require an identified element with a positive count for the selected metric. Scroll depths with no pages remain silent. Keyboard (Tab then arrows) and touch inspection are also available.

Older points without element identities may appear at original width without tooltips. They are omitted and counted at custom widths. Check coverage, revision and DOM changes. After a redesign, create a new revision rather than deleting previous records to try to realign points.

A SPA counts too many pages or captures too early

Send one Matomo page view per navigation. Avoid duplicating router integration, Tag Manager tags and manual calls. Heatlens.trackPageView restarts collection: do not add it to every trackPageView or component update.

Test next navigation, browser back/forward and delayed rendering on a dedicated campaign. Use delay, a trigger or manual capture when only visual readiness needs to be awaited. See the SPA workflow.

PNG unavailable, reduced or different from JSON

PNG requires a snapshot; recorded pages alone are insufficient. Check browser errors and try original width. PNG contains the reconstructed snapshot, selected metric and fold line; JSON preserves the filtered report's original data.

PNG limits are 2000 px width, 32760 px height and 16 million pixels, so long pages may be reduced. Media and CSS limits also apply to PNG. Reports cap each metric at 20000 distinct cells and report truncation.

Missing menu or rejected commands

Check activation, idSite and site access. Readers can view reports; write/admin users manage campaigns. A cross-site copy also requires write access at the destination.

Only the ten latest campaigns have menu shortcuts. Reload Matomo after creation, renaming or deletion; all campaigns remain in management. On a new site, use Matomo's link to temporarily hide its tracking setup page. An expired session or rejected CSRF protection requires signing in/refreshing, not disabling the protection.

Old interface after an update

Check the directory and version actually used by PHP, Docker mounts and unwanted nested folders. Reload web PHP for OPcache, regenerate matomo.js, clear Matomo caches as the web user and invalidate tracker CDN caches. CLI OPcache resets do not clear PHP-FPM/Apache caches. See the update procedure.

Missing notifications, repetition or purge

Notifications/repeats are processed hourly and purging daily when Matomo's scheduler executes them. Check actual scheduler runs and logs.

A notification requires a completed campaign, enabled personal preference, site access and working Matomo mail transport; also check mail filtering. Messages go to Matomo users, never visitors. Repetition requires its configured interval, completion and an active campaign; it creates a new campaign. Purging does not lower historical quota counters. Do not run a purge as a harmless diagnostic: it deletes eligible data. See maintenance.

Prepare a support request

Provide these details after removing private information:

• Heatlens, Matomo, PHP and browser versions; Docker or conventional installation.
• Reproduction steps, expected/actual result, timestamp and timezone.
• Site/campaign IDs, status, cap, tested rule, device, period, segment and revision.
• Relevant messages and log extracts; HTTP codes and blocked request names.
• A test page and, if useful, a screenshot containing fictitious data only.

Do not send passwords, cookies, token_auth, visitor exports, full configuration files or raw HAR files. Support may ask for a cleaned extract. Use the support portal, or contact@coderise.fr when it is unavailable. See the support policy.