Fix 'caching_sha2_password' MySQL Authentication Errors

You migrated a WordPress site or a PHP app to a new server, pointed it at MySQL 8, and now every page throws a database connection error. Locally it works fine. On the new server, PHP just refuses to talk to MySQL. If the error log mentions caching_sha2_password, this post is for you.

Symptom

The site shows "Error establishing a database connection," or if you're testing from the command line or a custom script, you get something more specific:

SQLSTATE[HY000] [2054] The server requested authentication method unknown to the client
mysqli::real_connect(): (HY000/2054): The server requested authentication method unknown to the client

Sometimes it's phrased slightly differently — Authentication plugin 'caching_sha2_password' cannot be loaded — but it's the same root cause. phpMyAdmin might even connect fine while your PHP app can't, which throws people off because "the database clearly works."

Cause

MySQL 8.0 changed its default authentication plugin from mysql_native_password to caching_sha2_password. It's a stronger, more modern hashing scheme, and it's a good change security-wise. The problem is client-side support:

• PHP versions built against an older libmysqlclient or an old bundled mysqlnd don't know how to speak caching_sha2_password — especially over a non-SSL connection, since the plugin needs either SSL or an RSA key exchange to send the password safely.
• This shows up most often right after a migration: you dumped a database from an older MySQL/MariaDB server, imported it into a fresh MySQL 8 instance on the new VPS, and the user accounts got recreated with the new default plugin.
• It also happens when a hosting stack mixes an old PHP build (common on legacy cPanel accounts still on PHP 7.2/7.3 via DSO or an older suPHP handler) with a freshly upgraded MySQL 8 server.
• MariaDB doesn't have this issue by default — it still ships with native password auth — so this is specifically a MySQL 8 + old-client problem, not a general "database won't connect" problem.

Fix

You have two real options: change the plugin on the MySQL side, or upgrade the client. Changing the user's auth plugin back to mysql_native_password is faster and almost always the right call for existing WordPress or legacy PHP apps — you're not giving up meaningful security since the connection is typically local (server-to-database on the same box or over an internal network anyway).

Option 1: Switch the database user's auth plugin (fastest)

Log into MySQL as root or an admin user, either via SSH or through phpMyAdmin's SQL tab in cPanel:

ALTER USER 'yourdbuser'@'localhost' IDENTIFIED WITH mysql_native_password BY 'the_same_password';
FLUSH PRIVILEGES;

Replace yourdbuser and the password with your actual WordPress database credentials from wp-config.php. If your app connects from a different host than localhost (say, a separate app server), update the host part of the user identifier to match — check with:

SELECT user, host, plugin FROM mysql.user WHERE user = 'yourdbuser';

That query is also the fastest way to confirm the diagnosis before you touch anything — if plugin shows caching_sha2_password for your app's user, you've found it.

Option 2: Change the server default for all new users

If you manage the MySQL server directly (VPS, not shared cPanel hosting where you can't touch my.cnf), you can set the default plugin server-wide so future accounts don't hit this:

[mysqld]
default_authentication_plugin=mysql_native_password

Add that under the [mysqld] section of /etc/my.cnf or /etc/mysql/mysql.conf.d/mysqld.cnf, then restart MySQL:

systemctl restart mysqld

Note this only affects new user creation — existing users still need Option 1's ALTER USER command to actually change their stored auth method.

Option 3: Upgrade PHP instead (if you'd rather keep caching_sha2_password)

If security policy requires keeping the newer plugin, the real fix is making sure PHP is compiled against a client library that supports it — PHP 7.4+ with a current mysqlnd generally handles caching_sha2_password correctly, especially when the connection uses SSL. In cPanel, switch the domain to a newer PHP version in MultiPHP Manager, then retest. This is the better long-term fix if you're on an old PHP version anyway, since you'll hit other compatibility walls with current WordPress regardless.

Quick sanity check after any fix

Test the connection directly before reloading the site, so you're not guessing:

mysql -u yourdbuser -p -h localhost yourdbname -e "SELECT 1;"

If that returns a clean result with no authentication error, your PHP app will connect too.

Prevention

The underlying lesson: MySQL and PHP version mismatches after a migration are one of the most common causes of database errors that look mysterious but have a one-line fix. Checking the plugin column in mysql.user takes ten seconds and saves an hour of guessing.

Frequently Asked Questions

Is switching back to mysql_native_password a security risk?

For most WordPress and PHP hosting setups, no — the database connection is local or restricted to trusted internal hosts, not exposed to the public internet. If your app connects to MySQL over an untrusted network, prioritize Option 3 (upgrading the client) instead so you can keep the stronger plugin.

Why does phpMyAdmin work but my PHP script doesn't?

phpMyAdmin typically ships with, or is configured to use, a more current MySQL client library than an older PHP build's bundled mysqlnd. It can negotiate caching_sha2_password just fine even when your application's PHP stack can't.

Do I need to change every database user, or just one?

Only the users your application actually connects with. There's no need to touch root or admin accounts you access exclusively through tools like phpMyAdmin or the MySQL CLI, since those already support the newer plugin.

Will this break anything in WordPress after I run the ALTER USER command?

No. The password stays the same — you're only changing how it's verified, not the credential itself. wp-config.php doesn't need any changes.

I'm on shared cPanel hosting and can't edit my.cnf — what are my options?

Use Option 1 (ALTER USER ... IDENTIFIED WITH mysql_native_password) through phpMyAdmin's SQL tab. It doesn't require server config access and takes effect immediately.