How do I troubleshoot a failed database upgrade in Matomo for WordPress?

First, check your system report whether it has any plugin_update errors like in the screenshot below. This error would be shown right in the beginning of the system report:

If that’s the case and the same error appears multiple times, please reach out to us and include the copied system report. There is a button at the top of the page to copy an anonymised version of the system report. If you prefer, you can also create an issue on our GitHub issue tracker instead of contacting us.

If such an error is shown, but the same error message isn’t shown multiple times, then the error might eventually go away the next time the updater runs. You could for example manually trigger the update again to see if it fails with the same error message as before (see below for how to trigger a database upgrade manually).

If that’s not the case, it seems like there is no issue and if previously an update error, it fixed itself by retrying the update.

How do I know if an upgrade is outstanding or currently in progress in the background?

Locate below entries in the system report to see if any upgrade is still outstanding or currently in progress.

How can I trigger a database upgrade manually?

From the system report click in the top on the “Troubleshooting” tab and then click on the button “Run updater”. This will trigger the update and if any error happens, WordPress should show a detailed error message. If an error happens, click on the button again and see if the same error appears. If that’s the case, reach out to us and include a copy of the system report.

The upgrade takes too long and always times out, can I execute the upgrade on the command line?

Yes, there are two ways:

  • Using the WordPress CLI: wp matomo update --force
  • Using the Matomo CLI (won’t work in MultiSite installations): cd /your/path/to/wp/wp-content/plugins/matomo/app && ./console core:update

Prefer to always execute the updates on the command line instead of executing them on demand using the UI? Add the following code to your wp-config.php and make sure to always run one of the above commands after executing the plugin

define( 'MATOMO_ENABLE_AUTO_UPGRADE' , false);

How do I view all outstanding database queries so I can execute them manually in the database directly?

This is currently only supported on the CLI when not using MultiSite. By executing the Matomo command core:update you will see a list of all database upgrades that need to be executed. You then also have the option to directly execute these updates on the command line.

cd /your/path/to/wp/wp-content/plugins/matomo/app
./console core:update
Previous FAQ: I cannot open the Matomo Reporting, Admin, or Tag Manager page, how do I troubleshoot it?