Runtime error: Mismatch source and target database charset error

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.

Alternative detailed procedure (a variation of the above procedure with details). In this case – it assumes your package charset/ source site charset is utf8mb4 and your target charset charset is different:

• Open your wp-config.php and add (e.g. if your package charset is utf8 or utf8mb4):

define( 'DB_CHARSET', 'utf8' );​

This will set your dB charset to use utf8 / utf8mb4 (makes it compatible with your package charset). Save it.

• Install WordPress Reset to easily reset your database from fresh install. This will create a new WordPress database based on utf8 / utf8mb4 encoding.
• Login to your freshly installed WordPress site and confirm that your dB charset is now using utf8mb4 after WordPress reset.
• If your dB charset is utf8mb4 – please install and activate latest Prime Mover version (if not yet installed).
• You can then restore the package within your package manager.

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

4. When “Migrate to UTF-8 database character set” checkbox is checked – it will force Prime Mover to export the database using utf8mb4 charset.
5. 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.

4. 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):

5. When “Migrate to hebrew database character set” checkbox is checked – it will force Prime Mover to export the database using hebrew charset.
6. 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:

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!