references/fixing-invalid-heatmap-data.md
Fixing the heatmap data warnings
An event carried a malformed $heatmap_data payload. The event itself survived — only heatmap data was discarded, so this shows up as heatmaps missing clicks/pages rather than missing events.
Category event, severity warning. Three variants tell you how much was lost:
| Type | What was discarded |
| ------------------------------------------- | -------------------------------------------------------------------------------------------- |
| invalid_heatmap_data | The entire $heatmap_data payload for that event — it didn't parse at all |
| rejecting_heatmap_data_with_invalid_url | One entry: its key (the page URL) was empty or not a string; other entries processed |
| rejecting_heatmap_data_with_invalid_items | One entry: its URL mapped to something other than an array of items; other entries processed |
What it means in your code
$heatmap_data is normally generated by posthog-js — hand-built payloads are almost always the source of these warnings. The expected shape:
{
$heatmap_data: {
'https://app.example.com/dashboard': [ // key: the page URL, a non-empty string
{ x: 120, y: 340, target_fixed: false, type: 'click' }, // value: an ARRAY of items
],
},
}
The classic bugs: a null/undefined URL variable interpolated into the key, a single item object where the array should be, or a stringified/otherwise mangled structure from a custom proxy or mobile bridge.
Diagnose
- Query the warnings with
posthog:execute-sql:SELECT timestamp, details FROM system.ingestion_warnings WHERE type IN ('invalid_heatmap_data', 'rejecting_heatmap_data_with_invalid_url', 'rejecting_heatmap_data_with_invalid_items') AND timestamp > now() - INTERVAL 7 DAY ORDER BY timestamp DESC LIMIT 20(narrow to a singletypeto isolate one variant). In thedetailsJSON, therejecting_*entries include the offendingheatmapUrlandsession_id;invalid_heatmap_dataentries carry theevent_uuidof the event whose payload failed entirely (read viaJSONExtractString(details, 'heatmapUrl')and friends). Therejecting_*types are debounced per session — each entry stands for a session's worth of skips. - Check the SDK version: pull
$lib/$lib_versionfrom the affected sessions' events (posthog:execute-sqlon the events table, filtered to the sampled session/distinct IDs) and compare against unaffected traffic. Warnings clustering on old posthog-js versions point to an outdated SDK producing a stale payload shape — the fix is an upgrade, not payload surgery. Mixed versions are common when some deploys/pages pin an old snippet. - Find the producer: if the app uses a current stock posthog-js, check for anything that rewrites events in flight (a capture proxy, a
before_sendhook, a custom transport). If$heatmap_datais built by hand (custom canvas apps, mobile), inspect that construction against the shape above.
Fix
- Outdated posthog-js: upgrade to the current version everywhere — hunt down pinned snippets and stale bundles so all pages ship the same version.
- Stock, current posthog-js: don't touch
$heatmap_data— remove or fix any middleware/proxy that rewrites it. - Hand-built payloads: match the shape exactly — page-URL string keys (guard against unset URL variables), arrays of
{x, y, target_fixed, type}items as values. Or better: capture the interactions as regular events and let PostHog's own heatmap capture do the heatmap part.
Verify
Re-run the affected pages/flows, re-query system.ingestion_warnings with posthog:execute-sql (filter type IN ('invalid_heatmap_data', 'rejecting_heatmap_data_with_invalid_url', 'rejecting_heatmap_data_with_invalid_items'), timestamp after your fix) — no new occurrences — and confirm the heatmap for the affected URLs starts accumulating data again.