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.

Important: Please do not change the wp-config.php of either the source or target in an attempt to fix this issue. This is not recommended by WordPress and could corrupt your site data.

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

Solutions

Solution depends on different migration scenarios. Choose one that best applies to your case:

Case 1:

  • If it is OK to migrate to a fresh WordPress install.

In this case, since it’s OK to migrate to a fresh WordPress install – make sure to create a fresh WP install using 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. Install a fresh WordPress target site by setting the DB_CHARSET to be exactly as the source site (origin site). You can set this via wp-config.php. Please refer to this procedure on getting the database charset used by the source site.
  2. On your new WordPress target site – install and activate latest version of Prime Mover.
  3. Finally now that the source and target site dB charset are the same – you can proceed to restore the package. There should be no more runtime errors related to dB charset.

Case 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.

Case 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