How to complete a blocked migration from Matomo Cloud to On-Premise

On-Premise

The migration process from Matomo Cloud to On-Premise involves installing Matomo, importing your database, and verifying your configuration. However, in some cases the migration is blocked due to two potential issues:

  1. The Cloud instance runs an alpha version.
  2. The exported database does not use a table prefix.
📝
Matomo Cloud uses version labels such as alpha as part of its internal release process. In this context, the label does not indicate that the version is experimental or unstable. These versions are production-ready and fully supported in Matomo Cloud. The same version can be installed for On-Premise.

This guide explains how to resolve the version mismatch and migrate successfully.

Install the Cloud alpha version for On-Premise

When migrating from Matomo Cloud to On-Premise, you may encounter a version error if your Cloud instance is running a newer version than the latest available On-Premise release. This can happen because Matomo Cloud updates versions that are not yet publicly released for On-Premise.

If your Cloud instance runs a newer version, the migration may fail with an error such as:

Your Matomo installation is running version 5.7.1… your database has been upgraded to 5.8.0-alpha…

This happens because the database schema version is newer than the On-Premise codebase.

  1. To resolve this, you need to install the same version as your Cloud instance. Matomo Cloud deploys production-ready and fully stable builds labeled as alpha. You can safely install the same version for On-Premise. See how to check your Matomo version.
  2. All builds (including alpha versions) are available at: https://builds.matomo.org/.
  3. You can also update your On-Premise instance to a newer version by enabling development releases (beta or release candidate versions) in Matomo system settings. Learn how to enable beta and RC updates in Matomo.

Migrate without a table prefix

Matomo does not require table prefixes. During installation, a table prefix (for example, matomo_) is simply pre-filled in the database configuration. This default value can be changed or removed.

In Matomo Cloud, table prefixes are not necessary to separate tables as each Cloud site runs on a dedicated database. If your On-Premise setup expects a prefix, you can install Matomo without a table prefix or modify the database dump to add a prefix before importing.

  1. Install the same version as Cloud (from https://builds.matomo.org/).
  2. Do not use a table prefix unless absolutely required.
  3. Import your database dump.

Once the version and database structure match your Cloud setup, Matomo should load without triggering errors or schema warnings.

Previous FAQ: Can I install Matomo on one server and track visits on websites that are hosted on other servers?