Troubleshooting Duplicator: Fixing wp-config.php Password Errors with Special Characters

Users of the Duplicator plugin have reported a recurring issue where a WordPress site fails after a migration, often showing a database connection error or a syntax error in the wp-config.php file. This problem is frequently traced back to how the plugin handles database passwords that contain special characters.

The Problem: Special Characters Causing Errors

When Duplicator's installer runs, it generates a new wp-config.php file. If your database password contains certain special characters—such as $, {, }, > (>), or the pound sterling symbol £ (£)—they may not be escaped or handled correctly. This can result in two main types of errors:

1. PHP Syntax Errors: Characters like $ and { have special meaning in PHP. If they are not properly escaped within the password string, PHP will try to interpret them as code, causing a fatal error like:
   unexpected ‘(‘, expecting variable (T_VARIABLE) or ‘{‘ or ‘$’ in /wp-config.php on line XX
2. Incorrect Character Encoding: The installer might convert special characters into their HTML entity equivalents. For example, a password like testing1£££££2111 might be written to the config file as:
   define( 'DB_PASSWORD', "testing1u00a3u00a3u00a3u00a3u00a32111" );
   This encoded version is not the same as the original password and will cause the database connection to fail.

Why This Happens

This appears to be a bug related to specific versions of Duplicator (e.g., version 1.3.10 was frequently mentioned in reports). The function that writes the password value to the wp-config.php file did not always properly escape or format strings containing these problematic characters. The issue was often fixed in subsequent developer or stable releases.

How to Fix It

If you encounter a database connection error immediately after a Duplicator migration, follow these steps to resolve the password issue.

Solution 1: Manually Edit wp-config.php (Quick Fix)

The fastest solution is to directly edit the wp-config.php file on your server.

1. Access your website's root directory via FTP, SFTP, or your hosting provider's file manager.
2. Locate and open the wp-config.php file for editing.
3. Find the line that defines the database password. It will look like this:
   define( 'DB_PASSWORD', 'your_password' );
4. Check the password value. If it contains HTML entities (like > or u00a3) or if the quotes are double ("") and your password has special characters, you need to correct it.
   • Replace any HTML entities with their actual character (e.g., change > back to >).
   • Ensure the password is wrapped in single quotes (' '), as this can prevent PHP from interpreting special characters within the string. For example:
     define( 'DB_PASSWORD', 'Mi)8J0={$(cH' );
5. Save the file and upload it back to your server, overwriting the old one.
6. Try to access your WordPress site or login again. The error should now be resolved.

Solution 2: Use a Simpler Password for Migration

If you frequently run into this problem, a reliable workaround is to temporarily change your database password to one that only contains alphanumeric characters (letters and numbers) before creating the Duplicator package. After the migration is complete, you can change the password back to your preferred, more complex one directly in the database and then update the wp-config.php file manually.

Solution 3: Check for a Plugin Update

This specific issue with special characters was acknowledged and addressed by the Duplicator team in updates following version 1.3.10. If you are using an older version, updating to the latest release of the plugin may permanently resolve the problem. Always ensure you are using the most recent stable version for the best experience.

Conclusion

Errors related to special characters in database passwords can be a frustrating hurdle during migration, but they are usually simple to fix. Manually editing the wp-config.php file to ensure the password is correctly formatted is the most direct solution. For ongoing use, keeping Duplicator updated is the best way to avoid such bugs.