Symptoms

When you migrate a site using Prime Mover 1.7.0+ you might get this runtime error during the restore/import process. The restore/import process is stopped with this runtime error.

Actual error message is something like:

Mismatch source and target database charset error. Source site charset [source-db-charset] cannot be restored to this database charset using [target-db-charset]

Causes

The source site database character set is different from the target site database character set. Since migration requires restoring the source database data to target database – the source and target database character set needs to be perfectly compatible or the same.

For example, if your database character set is UTF-8 (utf8mb4) , the target database needs to be in UTF-8 (utf8mb4) also. Or if you are using non-UTF8 charset such as greek charset – the target site needs to be in greek charset also.

Database character set is configured in WordPress via wp-config.php when you first install the site.

Please refer below for the solutions for this error. Take note these solutions can work for both single-site and multisite.

Solution #1: Create a fresh WordPress install to match the source site dB charset.

In this solution you can create a fresh WP install to match the source site database charset. This makes the target site dB charset to be same as the source site so you can restore the package. Detailed procedure of this solution are as follows:

  1. Open your target site wp-config.php.
  2. Change charset to match your source site dB charset. For example if the source site dB charset is latin1 then the DB_CHARSET should be set to: define( 'DB_CHARSET', 'latin1' );
  3. Install WordPress Reset to easily reset your WordPress database back to fresh install state. This will create a new WordPress database based on new target charset (e.g. latin1).
  4. Login to your freshly installed target WordPress site and confirm that your target dB charset is now the same with source site dB charset after WordPress reset. For example if the source site is latin1, the target site should also be latin1.
  5. [OPTIONAL] If the target DB charset is still not correct – delete the WordPress database from your MySQL server and re-install again WordPress from scratch.
  6. Finally now that the source and target site dB charset are the same – please install and activate latest Prime Mover version on your target.
  7. You can proceed to restore the package. There should be no more runtime errors related to dB charset.

Solution #2:

  • You cannot create a fresh WordPress install on target site. (e.g. if site is already existing and working)
  • The source site database character set is non-UTF-8 (e.g. tis620, greek, hebrew, etc.)
  • The target site database charset is UTF8 (utf8mb4).

This solution requires PRO version:

  1. Upgrade to Prime Mover PRO version in your source site.
  2. Make sure the source site database character set is non-UTF8 (please read dedicated FAQ section on what is non-UTF8 dB charset)
  3. Now that license is activated, launch export dialog and check “Migrate to UTF-8 (utf8mb4) database character set.“
  1. When “Migrate to UTF-8 database character set” checkbox is checked – it will force Prime Mover to export the database using utf8mb4 charset.
  2. You can then migrate this package to your target site that is using utf8mb4 database character set.

Solution #3:

  • You cannot create a fresh WordPress install on target site. (e.g. if site is already existing and working)
  • The source site database character set is UTF-8 (e.g. utf8mb4)
  • The target site database charset is non-UTF8. (e.g. hebrew, greek, tis620, etc.)

This solution also requires PRO version:

  1. Upgrade to Prime Mover PRO version in your source site.
  2. Get exactly the target site database charset value being used. Please refer to this FAQ details on getting this value.
  3. In your source site, add this constant to your wp-config.php to allow exporting database to a non-UTF8 charset:
define('PRIME_MOVER_CUSTOM_TARGET_CHARSET', 'YOURTARGET-CHARSET');

Replace YOURTARGET-CHARSET with the correct target dB charset value. For example if your target database charset value is hebrew, the constant should look like this:

define('PRIME_MOVER_CUSTOM_TARGET_CHARSET', 'hebrew');

Important: This constant should only be set if the source dB charset is already UTF-8 (utf8mb4) but the target dB charset is non-UTF8.

  1. Now that the constant is added, launch export dialog and you should see an option to export the dB using hebrew charset (based on the above example):
  1. When “Migrate to hebrew database character set” checkbox is checked – it will force Prime Mover to export the database using hebrew charset.
  2. You can then migrate this package to your target site that is using hebrew database character set.

FAQ: How to get the correct database character set used by your WordPress site?

  1. Login to your source site (where you have created the package).
  2. Make sure latest version of Prime Mover plugin is installed.
  3. Go to Prime Mover -> Advanced.
  4. Scroll down to the bottom until you see “Export site info“.
  5. Click “Export site info” button.
  6. Open the site info log.
  7. Search for [database_charset]
  8. This value is your source site database character set. For example:
In the above screenshot, the database charset value is utf8mb4.

FAQ: What are UTF8 and non-UTF8 database character sets?

UTF8 database character set today in modern WordPress installation is using utf8mb4 as default. The older UTF8 database charset are utf8mb3 or the utf8. It is not recommended to use old database UTF8 character sets because they are already deprecated.

Non-UTF8 database character sets does not have utf in their names. For example:

  • tis620
  • latin1
  • greek
  • koi8r
  • hebrew

And many others – complete list of supported database characters can found here.

FAQ: What about setting dB collations?

When Prime Mover exports the site on a specific DB charset – it should be migrated to a target site on that same character set also. And it uses the default collation associated with that charset. It is why Prime Mover will not ask for this value in export settings (only it’s character set).

After restoring the site and depending on the character set – WordPress chooses the best collation for that specific character set. (e.g. UTF-8) after restoring the site. This depends also on your MySQL version, etc.

This is also the reason why the dB collation is empty by default in wp-config.php. However when you first install a site – if there is really a need to provide a specific collation – please do it so in the wp-config.php file (before creating a fresh WordPress install).

Still getting runtime error?

If you are still getting runtime errors even after following the above steps – please generate logs and please provide them to technical support. Thank you!

Was this article helpful?
YesNo