# caching_sha2_password MariaDB 12: Fix MySQL 8 Client Problems

Source: https://srvscripts.com/guides/caching-sha2-password-mariadb-12/
Updated: 2026-10-03
Publisher: srvScripts (https://srvscripts.com/)

For years the most common cross-compatibility complaint between MySQL 8 and MariaDB was authentication: MySQL 8 made `caching_sha2_password` its default, MariaDB did not have the plugin, and any client library that only knew MySQL’s default failed against MariaDB with a message about an unknown plugin. MariaDB 12.1 added the plugin and 12.3 LTS ships it, which closes the gap but also introduces the opposite problem: accounts created on the new plugin now reject old clients. This guide sorts out both.

In short: Check which plugin the failing account uses with SELECT user, host, plugin FROM mysql.user.

**Short answer:** Check which plugin the failing account uses with `SELECT user, host, plugin FROM mysql.user`. If an old client cannot connect, move the account back with `ALTER USER ... IDENTIFIED VIA mysql_native_password USING PASSWORD('...')`; if a MySQL 8 connector insists on the new method, move the account to `caching_sha2_password` and make sure TLS or the RSA key pair is configured so the first handshake completes. Pin `default_authentication_plugin` in `my.cnf` so new accounts land on the plugin you intend.

## The errors you will see

An old client connecting to an account that uses `caching_sha2_password` gets a message along the lines of “Authentication plugin ‘caching_sha2_password’ cannot be loaded” or “The server requested authentication method unknown to the client”. A MySQL 8 client or connector that insists on the new method connecting to an account on `mysql_native_password` usually works, because the client falls back, but some minimal builds do not and produce a similar error the other way round.

A third variant appears when the first connection from a client on the new plugin is over an unencrypted connection: the plugin needs either TLS or an RSA key exchange for the initial handshake, and a server without the public key configured refuses. That one reads as “Access denied” with no further hint, which is why it is worth checking the plugin before chasing passwords.

## Find out which accounts use which plugin

```
mariadb -e "SELECT user, host, plugin FROM mysql.user ORDER BY plugin, user;"
mariadb -e "SHOW GLOBAL VARIABLES LIKE 'default_authentication_plugin';"
mariadb -e "SHOW PLUGINS" | grep -i sha2
```

On a server upgraded from 11.x every existing account remains on `mysql_native_password`. Only accounts created after the upgrade, and only if the default plugin was changed or the creating tool specified it, will be on `caching_sha2_password`. On cPanel and DirectAdmin the panel creates database users through its own API and, as of the current builds, keeps them on the native plugin; check a recently created account on your server rather than assuming, since this could change with a panel release.

## Fix for an account that old clients cannot reach

Move the account back to the native plugin. This does not weaken security meaningfully on a hosting server where connections are local or over TLS:

```
ALTER USER 'app'@'localhost' IDENTIFIED VIA mysql_native_password USING PASSWORD('the-password');
FLUSH PRIVILEGES;
```

The MariaDB syntax is `IDENTIFIED VIA plugin USING PASSWORD(...)`; the MySQL-style `IDENTIFIED WITH plugin BY` also works on 12.x for compatibility. To prevent new accounts landing on the new plugin, set the default explicitly in `my.cnf` under `[mysqld]` and restart:

```
default_authentication_plugin = mysql_native_password
```

## Fix for clients that must use the new plugin

If a customer’s application stack is built for MySQL 8 and refuses to use the native plugin (some managed Java and Go connectors are configured this way), move that account forward instead:

```
ALTER USER 'app8'@'%' IDENTIFIED VIA caching_sha2_password USING PASSWORD('the-password');
```

Then make sure the first connection can complete the handshake. The clean way is TLS, which every hosting server should already have for remote database access:

```
mariadb -e "SHOW GLOBAL VARIABLES LIKE 'have_ssl';"
grep -E '^(ssl-ca|ssl-cert|ssl-key|require_secure_transport)' /etc/my.cnf /etc/my.cnf.d/*.cnf
```

If TLS is not configured, the plugin’s RSA key-pair exchange needs `caching_sha2_password_private_key_path` and `caching_sha2_password_public_key_path` pointing at a key pair the server can read. Generate one with `openssl genrsa` and `openssl rsa -pubout`, set the paths, restart, and the client will fetch the public key on first connect. Once a client has authenticated successfully, the server caches the credential and subsequent connections from that client are fast even without TLS.

## PHP specifics

PHP’s `mysqlnd` driver has supported `caching_sha2_password` since PHP 7.4, so any PHP version a hosting server should be running in 2026 is fine. The failure cases are PHP builds compiled against the external `libmysqlclient` (rare on cPanel and DirectAdmin, which use mysqlnd) and very old Composer dependencies bundling their own MySQL client. Check the driver:

```
php -i | grep -iE 'mysqlnd|Client API'
```

If it says mysqlnd with a version of 7.4 or later, PHP is not the problem, and the account or handshake is.

## Replication and tooling

A replica connecting to a primary account on the new plugin needs a connector that supports it; `mariadb` and `mariadbd` 12.x do. Backup tools built on `mysqldump` from an older MySQL client package, Perl `DBD::mysql` compiled a decade ago, and monitoring agents with bundled clients are the usual stragglers. Our [MySQL health snapshot script](/scripts/mysql-health-snapshot/) uses the server’s own `mariadb` client and is unaffected, but audit anything else that connects with a fixed binary.

**Common pitfall.** Changing `default_authentication_plugin` on a live shared server and forgetting that the panel creates accounts constantly. Every customer who creates a database user after the change gets the new plugin, and the first one running a legacy PHP application opens a ticket. If you set the default to the new plugin at all, do it only after confirming every PHP version, phpMyAdmin build and backup tool on the server handles it.

## Verify

Test the specific account with the specific client that was failing, and confirm the plugin in the same command:

```
mariadb -u app -p -h 127.0.0.1 -e "SELECT CURRENT_USER(), @@session.ssl_cipher;"
mariadb -e "SELECT user, host, plugin FROM mysql.user WHERE user='app';"
```

A successful login plus the expected plugin name, and a non-empty cipher if you set up TLS, closes the ticket. Record which accounts use which plugin in your migration notes; when the server moves to the next LTS the question comes up again.

## Caching_sha2_password MariaDB at a glance

**Official documentation:** [MySQL reference manual](https://dev.mysql.com/doc/), [MariaDB documentation](https://mariadb.com/docs/), [Linux man pages](https://man7.org/linux/man-pages/).

**Related guides:** [AutoSSL failed: fixing DCV errors, CAA records, CDN proxies and blocked /.well-known/](https://srvscripts.com/guides/autossl-failed-cpanel-dcv-caa-cdn/) · [Replacing cxs: malware scanning with LMD (maldet), ClamAV and ImunifyAV on hosting servers](https://srvscripts.com/guides/cxs-replacement-malware-scanning/) · [MariaDB support timeline 2026–2029: which LTS should your servers run?](https://srvscripts.com/guides/mariadb-support-timeline-2026-2029/).

## Frequently asked questions

### Does caching_sha2_password on MariaDB 12 affect cPanel or DirectAdmin database users?

Not by default. Both panels currently create database users on mysql_native_password, so only accounts created manually, by tools that specify the plugin, or after changing default_authentication_plugin use the new method.

### How long does switching an account between authentication plugins take?

It is immediate: a single ALTER USER statement rewrites the credential and the next connection uses the new plugin without a server restart; only changing the server default in my.cnf needs a restart.

### Can I undo a move to caching_sha2_password?

Yes. Run ALTER USER with IDENTIFIED VIA mysql_native_password and the same password, and old clients connect again; the password must be supplied again because the stored hash format differs between the two plugins.