Insights, guides, and best practices for privacy-first marketing intelligence.
A warning in System Check when your PHP is current is almost always about your database, not PHP. And the PHP Deprecated lines flooding your archiver log aren't errors at all. Here's how to tell what each one is really saying, and what's worth doing about it.
Self-hosting Matomo means the admin login sits behind nothing but a username and password, and on some servers files that should be private are downloadable in the browser. Matomo auto-protects its private directories but not the web root, and on Nginx it protects nothing at all. Here's the hardening that actually matters on Matomo 5, in priority order, without locking out your tracker or your own archiving.
Renaming matomo.php to a neutral path doesn't help: ad blockers match on hostname and path together, so as long as hits go to analytics.yourcompany.com the rule still fires. The durable fix is to serve Matomo Tag Manager fully first-party through a reverse proxy. Here's how, including the Cloudflare IP gotcha that collapses every visitor to one location.
Matomo's import_logs.py rarely tells you what's actually wrong. A JSONDecodeError almost always means --url is pointing at the wrong place, every line counted as an 'invalid log line' means your log format doesn't match, and a piped import that records nothing is usually just buffering. Here's how to read each failure and fix it on Matomo 5.x.
Matomo Ecommerce is two separate things wearing one name: a setting that makes the reports exist, and tracking calls that fill them. Most stores only have the first. Here's why your Orders and Products reports read zero, and how to wire up the half that's actually missing.
If every site reports into the same Matomo, or a second tracking snippet kills the first, or you're hunting for a per-site token_auth that doesn't exist, you're tangling three things Matomo keeps strictly separate: measurables, domains, and tokens. Here's the model that fixes all of it.
Matomo's cookieless config_id isn't a classic fingerprint, ePrivacy and GDPR are two separate questions, and the reason 'Refuse' doesn't stop your tracking is almost always a double-injected tracker. Here's the config behind all three. Not legal advice, just the mechanics.
If your Matomo visits doubled overnight, your server-side tracker reports two to three times what the JavaScript tag does, or you're drowning in Direct Entry, one-page, zero-second hits, bots are almost certainly the cause. Matomo already filters the honest ones. Here's how to handle the rest and clean up the reports you already have.
The little flag next to each visitor in Matomo isn't guessed from language or timezone; it's the country your geolocation database resolved from the visitor's IP. So a wrong flag is almost always a geolocation problem, not a flag problem. Here's how country detection actually works, why one looks wrong, and how to swap the icons.
If your self-hosted Matomo resolves visitors to 'Unknown' or one default country, you're almost always missing a GeoIP2 database. The old .dat downloads are dead and GeoLite2 now needs a free license key. Here's the current Matomo 5.x setup, why it broke, and how to keep it updating itself.
core:archive dies on month and year with a DataTable.php fatal, MySQL CPU pins for no reason, and raising memory_limit never helps. It's almost always one thing: archiving, not tracking, is what makes Matomo heavy. Here's why more RAM doesn't fix it and what to tune instead.
Two campaign-tracking symptoms come up constantly in Matomo 5.x: the Campaigns report stays empty even though tagged links get visits, and the visit log shows ?gad_source=1 instead of your UTM parameters. Neither is usually a bug. Here's the mechanism behind each and exactly how we fix them.
Matomo's database errors look cryptic, but the SQLSTATE code in the message tells you exactly which half of the problem you're in. Here's how to read [1045], [2002], and the missing-privilege warnings, and the specific fix for each in Matomo 5.x.
Matomo's visitor numbers stop being mysterious once you know how it decides who is who and when it starts counting again. Here's the recognition model underneath unique visitors, visits, and unique pageviews in Matomo 5, plus why daily uniques don't sum and how server-side tracking splits one person into many.
The event happened on your server, not in a browser, so the JavaScript snippet never saw it. Here's how to record it with Matomo's HTTP Tracking API: the parameters that actually matter, when you need token_auth, and whether you can stop strangers spamming the public matomo.php endpoint.
Matomo loads fine on its direct port, then throws a 502 Bad Gateway the second Caddy or Nginx is in front of it. The proxy log says 'connection refused', and that one word tells you exactly what's wrong: your proxy is dialing the host-published port from inside the Docker network, where it doesn't exist. Here's the fix, plus how to size the box Matomo runs on.
Your scheduled core:archive job either errors out with 'the response was empty' or runs clean, prints 'Processed 0 archives,' and leaves dashboards frozen on yesterday's numbers. The two symptoms have different causes. Here's how we diagnose and fix both on Matomo 5.
Matomo's System Check tells you to run core:archive on a schedule, and your dashboards have started to crawl. Both are the same thing: browser-triggered archiving doesn't scale. Here's how to turn it off and run the archiver on cron correctly on Matomo 5.
After upgrading to Matomo 5.6–5.8 (or installing through Softaculous), archiving dies with "Table '…_log_bot_request' doesn't exist - in plugin BotTracking". The BotTracking plugin's table never got created. Here's why, and how to put it back so the error doesn't come straight back.
Matomo 5.8 added an 'AI Chatbot Requests' column to the All Websites dashboard plus a set of AI Assistants reports, and the names all sound the same. Here's what each of the three reports measures, why the chatbot numbers look so small, and how to get that column off your dashboard without switching tracking off.
Setup is two jobs, not one. Turning the plugin on takes ten minutes. Making the screenshot Matomo produces actually look like your live site is the longer half. Here's the path we walk through on every client setup.
Three tools that look similar in screenshots but solve different problems. Here's how we pick between them on client work, and what each is honestly good at.
Matomo tracks campaigns and runs multi-touch attribution, but it doesn't know what your ads cost. That one missing input is why every paid-media review ends in a spreadsheet.
Matomo heatmap screenshots show black rectangles where your hero video, autoplay product reel, or background loop should be. The clicks are fine. Here's why the video doesn't paint and how we deal with it.
Matomo heatmap screenshots can show tooltips, dropdowns, and badges floating at the top-left of the page when their containers don't have a positioning context. The clicks land where you'd expect; the overlays drift. Here's why it happens and how we deal with it.
Fixed and sticky headers either repeat down the page or freeze across the middle of Matomo heatmap screenshots, because Matomo renders the captured DOM as one tall image with no consistent viewport for them to anchor to. Here's why it happens and how we deal with it.
Matomo heatmap screenshots break when your page uses relative paths. The renderer resolves them against Matomo's host instead of yours, so images, stylesheets, and fonts 404. Here's why it happens and how we deal with it.
Matomo heatmap screenshots show broken-image placeholders when the image URLs in the captured snapshot won't resolve at view time: expired signed URLs, hot-link protection, or a CDN that blocks the request. The click data is fine. Here's why it happens and how we deal with it.
Cal.com, Calendly, YouTube, and HubSpot embeds capture as tiny default-height frames in Matomo heatmaps, often with an internal scrollbar. The clicks pile up on empty space and any insight into what visitors did inside the embed is lost. Here's why it happens and how we deal with it.
Matomo heatmap screenshots fall back to Times New Roman or Arial when your @font-face files get blocked by CORS, locked to a hosted-font provider, or loaded after the snapshot is taken. Here's why it happens and how we deal with it.
Matomo heatmap screenshots go black or blank below a certain line when a sidebar, tabbed panel, or any container with a capped height clips its overflow during capture. The clicks are still recorded, just landing on empty space. Here's why it happens and how we deal with it.
Matomo heatmap screenshots silently clip everything inside scroll containers and overflow:hidden wrappers. Sidebars, modals, and 'scrollytelling' layouts disappear past their visible edge, and clicks land on whatever was on screen at capture time. Here's why it happens and how we deal with it.
Heatmap screenshots break on most modern sites because of how Matomo serializes and re-renders the DOM. Here are the patterns we kept running into, and a small open source extension we built to handle them.
Matomo is the right foundation for privacy-first web analytics. The bridges to the rest of the marketing stack mostly aren't there. That gap is what we're building into.
Matomo heatmap screenshots break because the page is saved as a DOM snapshot, then reconstructed later with CSS, fonts, images, and layout still coming from your site. Here's what causes each issue and how to fix it.