Understanding and Resolving Matomo Errors in WordPress

Matomo for WordPress gives you Google Analytics-style reports without sending visitor data to a third party, which is exactly why community sites, membership sites and anyone with European members keep picking it. It also runs an entire analytics engine inside your WordPress install, so when it breaks, it breaks in ways a lightweight tracking plugin never would: reports stop updating, the dashboard throws PHP errors, or tracking silently records nothing. Nearly every one of those failures comes down to four causes: archiving not running, the tracker being blocked, missing PHP or MySQL requirements, or a conflict with caching and security plugins.

We have supported Matomo on enough BuddyPress and WooCommerce sites to have a short diagnostic routine. This guide walks through it in the order we actually use, with the settings paths, constants and commands for each fix.

Which Matomo are you running?

Before fixing anything, confirm which setup you have, because the fixes differ.

Setup	What it is	Where errors show up
Matomo Analytics (the “Matomo for WordPress” plugin)	Full Matomo installed inside WordPress, using your WordPress database and WP-Cron	Matomo Analytics → Diagnostics, the WordPress debug log
Connect Matomo (formerly WP-Matomo)	A bridge plugin that adds the tracking code for a separate Matomo On-Premise or Cloud instance	Your Matomo server’s logs, not WordPress
Manual tracking snippet	Tracking code pasted into the theme or a header plugin	Browser console only

This article is about the first one, the in-WordPress plugin (version 5.x at the time of writing, which requires PHP 7.2.5 or newer, MySQL 5.5 or newer and at least 128 MB of PHP memory, with 256 MB recommended per the plugin listing). If you run Connect Matomo, most “WordPress” errors are really server-side Matomo errors and belong in Matomo’s own troubleshooting docs.

Start at the Diagnostics page

Matomo Analytics → Diagnostics (called System Report in older versions) is the single most useful screen, and most people never open it. It tells you:

• PHP version, memory limit and max execution time, with warnings when they are too low.
• Whether the required PHP extensions are present (mbstring, json, dom, xml, gd for graphs in emails, and curl for the geolocation database download).
• File permission problems in wp-content/uploads/matomo/ and wp-content/cache/matomo/.
• Under Crons, when matomo_scheduled_archive last ran and whether it completed. This line alone resolves half of the “reports are empty” tickets.
• Known incompatible plugins it has detected.

Copy the whole report before changing anything. If you end up opening an issue on the plugin’s GitHub, they will ask for it, and it also gives you a baseline to compare against after each fix.

Error 1: reports are empty or stopped updating

Matomo stores raw visits immediately but only builds the reports you see (visits per day, top pages, referrers) through a process called archiving. In the WordPress plugin, archiving runs hourly through WP-Cron as the matomo_scheduled_archive event. If the cron fails, the Visits Log and Real Time reports still fill up but everything else stays flat.

Confirm it is archiving, not tracking

Open Matomo Analytics → Reporting, then Visitors → Visits Log. If you see recent visits there but the Overview shows zero, tracking works and archiving does not. If the Visits Log is also empty, skip to the tracking section.

Fix: get WP-Cron running reliably

WP-Cron only fires when someone loads a page, so a low-traffic site or one behind a full-page cache may go hours without a run. The reliable fix is a real cron job. Disable the page-load trigger by adding this to the wp-config file:

define( 'DISABLE_WP_CRON', true );

Then add a server cron entry (cPanel → Cron Jobs, or crontab -e) that calls WP-Cron every five minutes and, separately, runs the Matomo archive task hourly:

*/5 * * * * cd /var/www/example.com && wp cron event run --due-now --quiet
5 * * * * cd /var/www/example.com && wp cron event run matomo_scheduled_archive --quiet

If WP-CLI is not available, the first line can be curl -s https://example.com/wp-cron.php?doing_wp_cron >/dev/null. Hosts such as Seravo document this exact setup for Matomo because it is the fix that works most often.

Fix: disable async archiving

The plugin tries to run archiving in a background PHP process so it does not block the cron request. On some hosts (Uberspace is a documented case, and any host where the CLI PHP cannot read the database credentials) that background process fails. Force it back to synchronous mode:

define( 'MATOMO_SUPPORT_ASYNC_ARCHIVING', false );

Then click Archive reports under Diagnostics → Troubleshooting to run one manually. If that completes, the cron will too.

Fix: raise limits

Archiving a month of data for a busy site needs memory and time. If the manual archive dies with a blank screen, set memory_limit = 256M and max_execution_time = 300 in PHP, or in the wp-config file:

define( 'WP_MEMORY_LIMIT', '256M' );
define( 'WP_MAX_MEMORY_LIMIT', '512M' );

Error 2: nothing is being tracked

If the Visits Log is empty too, the JavaScript tracker is not reaching the site. Work through these in order.

1. Tracking is not enabled. Go to Matomo Analytics → Settings → Tracking and confirm Tracking mode is set to Default (or Tag Manager if you use it), not Disabled. A fresh install sits on Disabled until you click Activate tracking on the Get Started page.
2. Your own visits are excluded. By default, logged-in administrators are not tracked. Test in a private window while logged out, or change “Track users with the following roles” under the same settings page.
3. An ad blocker is eating the request. Browser blockers filter requests to matomo.js and matomo.php by name. Open the browser’s Network tab, filter on “matomo” and look for a blocked request. Matomo’s settings page offers renamed tracker files (the “Use a different tracker file” option) that sidestep common filter lists; it is a legitimate setting, not a trick, because you are tracking your own first-party site.
4. The tracking code never reached the page. View the page source and search for _paq. If it is missing, a caching plugin served a copy of the page generated before tracking was enabled. Clear the page cache (WP Rocket, LiteSpeed Cache, W3 Total Cache and the host cache if any). If the theme does not call wp_head() or wp_footer(), the code has nowhere to print; switch to a theme that does, or use the Manually option in Tracking settings and paste the code yourself.
5. A security plugin blocks the endpoint. Wordfence, a WAF rule or a .htaccess hardening snippet sometimes blocks direct access to PHP files under wp-content, which includes wp-content/plugins/matomo/app/matomo.php. Whitelist that path, or switch the tracker endpoint in settings to the REST API route, which goes through /wp-json/matomo/v1/hit/ and is rarely blocked.

Error 3: PHP fatal errors and white screens

These have consistent causes.

• “Allowed memory size exhausted” while opening a report. Raise the limits as above. Matomo also caches heavy report data under wp-content/cache/matomo/; confirm PHP can write there.
• Missing extension errors (“Class DOMDocument not found”, mbstring warnings). Install the extension through your host’s PHP selector, then reload Diagnostics.
• Errors after a PHP upgrade. Matomo 5 supports PHP 8.x, but an old plugin version left on PHP 8.3 or 8.4 will fail with deprecation notices turned into fatals. Update the plugin before upgrading PHP, not after.
• Database errors such as “Table ‘wp_matomo_archive_numeric_2026_08’ doesn’t exist” or “CREATE command denied”. Matomo creates monthly archive tables on the fly and needs CREATE, ALTER, INDEX and DROP privileges on the WordPress database. Shared hosts sometimes strip these from the WordPress user. Grant them, then run Diagnostics → Troubleshooting → Install or update database tables.
• Custom content directory. Bedrock and similar setups that move wp-content confuse the plugin’s path detection. Define MATOMO_UPLOAD_DIR and MATOMO_CACHE_DIR in your config to point at writable directories.

To capture the actual error rather than a white screen, turn on logging temporarily:

define( 'WP_DEBUG', true );
define( 'WP_DEBUG_LOG', true );
define( 'WP_DEBUG_DISPLAY', false );

Then reproduce the problem and read wp-content/debug.log. Turn the constants off again when you are done.

Error 4: plugin conflicts

The Diagnostics page lists known conflicts, but these are the ones that reach our support queue most:

• Full-page caches serve stale pages without the tracker, or cache the tracker’s 204 response. Exclude /wp-json/matomo/ and matomo.php from caching rules.
• Script optimisers (Autoptimize, WP Rocket’s JS delay, Perfmatters) defer or combine matomo.js, which can mean the pageview fires late or never. Exclude it from delay and combine rules.
• Cookie consent plugins that block scripts until consent. Correct behaviour, but remember Matomo can run cookieless: enable “Disable cookies” under Tracking settings and many consent tools will let it load without a banner click, depending on your legal advice.
• WooCommerce on older Matomo versions caused archive failures tied to ecommerce tracking. Update both plugins; the fix shipped in the 4.x line.
• Multisite. The plugin works on Multisite, but each site archives separately and the Tag Manager feature is not available. Expect the cron load to multiply by the number of sites.

When you cannot spot the culprit, the old method still works: switch to a default theme, disable everything except Matomo, confirm it works, then re-enable plugins in batches.

Performance: when Matomo is too heavy for the host

Matomo inside WordPress shares PHP workers and database with your site. Above roughly 50,000 to 100,000 pageviews a month on shared hosting, archiving starts to compete with real visitors, and on a busy BuddyPress community with activity streams and notifications already hitting the database, the contention shows up as slow page loads every hour on the hour.

Options, roughly in order of cost:

1. Move archiving to the server cron as above, so it never runs inside a visitor’s request.
2. Under Matomo Analytics → Settings → Advanced, reduce data retention by deleting raw visitor logs older than 180 days; the archived reports stay.
3. Move to a separate Matomo On-Premise install on its own small server and switch the WordPress side to Connect Matomo. Your data stays yours, but the heavy lifting leaves the WordPress box.
4. Matomo Cloud, if self-hosting is not worth your time.

If you are already paying for managed hosting and the site is slow for other reasons, a performance review that looks at the whole stack usually finds Matomo is one of several contributors rather than the only one.

Frequently asked questions

Why does Matomo show visits in Real Time but the dashboard stays at zero?

Archiving has not run. Check Diagnostics for the last cron run, then set up a server cron or disable async archiving as described above.

Is it safe to delete the Matomo tables to start over?

Only if you can lose the history. Deactivating and deleting the plugin removes its data by default; a clean reinstall recreates the tables. Export any report you need first.

Does Matomo for WordPress need a cookie banner?

With cookies disabled, IP anonymisation on and no cross-site tracking, many European data protection authorities treat Matomo as exempt from consent. That is a legal judgement for your jurisdiction, not a technical one, so confirm it for your case.

Can I run Matomo and Google Analytics together?

Yes, they do not interfere. Sites migrating off GA often run both for a quarter to compare numbers before removing the GA tag.

Where to start

Open Matomo Analytics → Diagnostics and read the Crons section and any red warnings. Nine times out of ten that points at archiving, and a server cron plus MATOMO_SUPPORT_ASYNC_ARCHIVING set to false fixes it in ten minutes. If tracking itself is dead, test logged out in a private window with the Network tab open, then clear caches and check the security plugin. Keep the debug log on only while you are looking, update Matomo before PHP, and move archiving off the page-load cron on any site you care about.