Evan Genest's Learning Log

Web developer notes emphasizing LAMP, Symfony, PHP, Javascript, Drupal, and Node.

This is an Eleventy project created from the eleventy-base-blog repo.

Troubleshooting Tips for Matomo Web Page Analytics


What this article is

I don't recommend reading this article, it is a personal souvineer so I can look back in the future and see where I have been, what I was learning month to month. Now I am learning the web analytics platform Matomo.

Best place to read about Matomo

If you want to learn about Matomo, go to the official help site itself. Make this page your home page for explorations, it leads to all of the good stuff: https://matomo.org/help/

The Help docs are readable, organized, clear. And if you go down the many roads, the site is enormous, but upon first arriving, it doesn't feel enormous. You only encounter the enormity once you go to your section of interest. Once there, things can go deeper and deeper. But only if you keep digging. The overall UX is excellent, in other words: the site opens up like a fractal in a video game where you walk closer and closer to a distant cliff in the video game and the landscape resolution keeps improving.

What follows is a random fly by of Matomo's docs.

Glossary of Analytics Terms

There is a helpful glossary with ~200 terms.

Ten common examples to troubleshooting actions

Find the pattern in where to look, what to check, what to ask. These solutions can be extended to other, seemingly novel problems:

  1. After updating, Matomo stopped working
  1. General strategy for Matomo errors: check PHP errors
$ php -r "phpinfo();" | grep php.ini
$ php -r "phpinfo();" | grep error
  1. You can always reinstall. Remove the Matomo directory and load the latest version
  2. The dashboard looks weird or is missing styling or portions
  1. Some pages are not being counted
  1. IP address (and location, therefore?) is wrong. Like it's always the same IP.
    Proxy in front of your server may cause this.
    Using the API may cause this.
    See the docs for ways to overwrite this with the correct IP address.
  2. Geo-location not correct
  1. Referrer information is incorrect or missing
  1. Matomo just gives a white-screen-of-death or a 500 error
  1. You are getting more discrepency than expected between Matomo and another web analytic (i.e. Google Analytics)
    Causes of discrepent tracking:

General places to go

Issues at GitHub


Forum: Most-asked questions in the forum

It is awesome to see that the forum is sortable by most viewed, most replied, and date.

Most highly viewed in General thread:
Tag Manager questions, generally
React app
Tag manager blank screen
Tracking Wordpress user ID with Tag Manager
How to get data attribute in Custom JavaScript variable?
Click trigger target data attribute


There are 950 Frequently Asked Questions.
The categories of FAQs are

New to Matomo
How to
Plugins and Themes
Matomo on Windows
Tag Manager
Video & Audio Analytics
Users Flow
A/B Testing – Experiments
Advertising Conversion Export
Custom Reports
Roll-Up Reporting
Form Analytics
Heatmap and Session Recording
SEO Web Vitals
Search Engine Keywords Performance
Multi Channel Conversion Attribution
SAML Login
Log Analytics tool
Mobile App
Matomo for WordPress

Tag Manager videos

These are in the Help Centre
Total running time (for 11 videos): 66 minutes

Tag Manager videos table of contents:

01. Introduction to Tag Manager systems
02. Introduction to Matomo Tag Manager
03. Deploying your first Container
04. Tag Manager use case
05. Tags
06. Triggers
07. Variables
08. Versions
09. Preview, Debug, Publish
10. Data Layers
11. Training conclusion

Web Analytics videos

These are in the Help Centre.
Total running time (for 19 videos): 118 minutes
Table of contents:

Section one – understanding web analytics

01. What is digital analytics?
02. What is Matomo Analytics?

Section two – understanding Matomo features

03. Making sense of the Matomo reports
04. Tracking Goals
05. Tracking Events
06. Segments
07. Funnels for Goals
08. Users Flow
09. Heatmaps & Session Recordings
10. Media Analytics
11. Form Analytics
12. Search Engine Keywords Performance
13. Custom Reports
14. Roll-Up Reporting
15. Multi Channel Conversion Attribution
16. A/B Testing
17. Activity Audit Log
18. White Label
19. Training conclusion

Secret Videos

These are not secret, they are just one level deeper in the site navigation

Videos in the User Guides:

Welcome to Matomo
How to Install Matomo Analytics using Cloud-Hosted
How to Install Matomo Analytics using Self-Hosted
Matomo’s Visitors Feature
Matomo’s Behaviour Feature
Matomo’s Acquisitions Feature
Matomo’s Ecommerce Feature
Matomo’s Goals Feature
Matomo’s Multi Attribution Feature
Matomo’s Funnels Feature
Matomo’s Media Analytics Feature
Matomo’s A/B Testing Feature
Matomo’s Form Analytics Feature
Matomo’s Heatmaps Feature
Matomo’s Session Recordings Feature
Matomo’s Custom Reports Feature
Matomo’s Tag Manager
Matomo and the GDPR
Importing Google Analytics data into Matomo
Matomo Analytics for WordPress

Random things I noted

Your db is not infinite! Periodically delete the older data

If you have properly setup the auto archiving script (see important note), you will still access all historical reports (even when RAW data is deleted). Delete the raw data in SQL, or the command line, or in the GUI dashboard.

Random fact from the forums: CDN can affect analytics

In Matomo page views can become less than Visitors, due to the CDN

Going 100% Cookieless

To avoid needing a banner on sites, users can go cookieless.

Cookieless options in Matomo:

Language of questions asked at the Matomo site

The site is mainly in English but the user forum posts for the last 30 days are also: 15 German, 4 French, 52 Spanish, 34 Italian