caching_sha2_password MariaDB 12: Fix MySQL 8 Client Problems

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.

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 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, MariaDB documentation, Linux man pages.

Related guides: AutoSSL failed: fixing DCV errors, CAA records, CDN proxies and blocked /.well-known/ · Replacing cxs: malware scanning with LMD (maldet), ClamAV and ImunifyAV on hosting servers · MariaDB support timeline 2026–2029: which LTS should your servers run?.

Frequently asked questions