How do I fix a failed database update?

Sometimes, running the database update after upgrading Matomo to a newer version can fail. This guide explains how to safely re-run the database update commands if the update didn’t complete successfully. Following these steps will help ensure your Matomo database is correctly updated.

Step 1 – Fix the issue that caused the failed database update

Simply re-running the database update may not work if there was something specific that caused the update to fail.
In some cases you will need to increase the wait_timeout of your database server to ensure that the queries don’t time out. In other cases, you may need to re-upload all of the Matomo codebase files to ensure that there are no corrupted files causing an issue.

Step 2 – Rollback the version numbers stored in the Matomo database

We can achieve this by running the following queries directly on the Matomo database:

For updating from Matomo 5 and higher

If you were updating from one version of Matomo 5 to a newer version of Matomo 5, you will need to run the following query:

UPDATE matomo_option set option_value = '5.0.0' where option_value like '5.%';

Note: Here we’re rolling the versions back to an older version than what was previously installed. The reason for this is that there may be plugins that only have a 5.0.X version which need to be updated.
If you’re using an RC or Beta version of Matomo 5, you need to instead roll back to an earlier RC or Beta version to re-run any updates. For example the version to set in the database would be similar to 5.0.0-rc1.

For updating from Matomo 4 and higher

If you were updating from one version of Matomo 4 to a newer version of Matomo 4, you will need to run the following query:

UPDATE matomo_option set option_value = '4.0.0' where option_value like '4.%';

Note: Here we’re rolling the versions back to an older version than what was previously installed. The reason for this is that there may be plugins that only have a 4.0.X version which need to be updated.

For updating from Matomo 3

If you were updating from Matomo 3 to Matomo 4, you will need to run the following query (If you were using an older version than Matomo 3.13.6 then use that version number in the query below):

UPDATE matomo_option set option_value = '3.13.6' where option_value like '4.%';

Once this has been done, you can then trigger the database update:

./console core:update