Fixing "Authentication plugin 'caching_sha2_password' cannot be loaded"

Posted by Kyle Hankinson July 9, 2026

---

You point an application at a MySQL 8 server and it fails before a single query runs:

ERROR 2059 (HY000): Authentication plugin 'caching_sha2_password' cannot be loaded:
/usr/lib/mysql/plugin/caching_sha2_password.so: cannot open shared object file:
No such file or directory

That is the real output from connecting a MySQL 5.6 era client to a stock mysql:8.0 Docker container. Nothing is wrong with your password or your grants. The client library is simply too old to speak the authentication protocol the server now uses by default.

What changed, and in which version

MySQL 8.0 switched the default authentication plugin from mysql_native_password (a SHA-1 scheme dating back decades) to caching_sha2_password, which uses SHA-256 and requires either a secure connection or an RSA key exchange during the first login. Every user created on a default MySQL 8 server gets the new plugin. On a fresh mysql:8.0 container:

SELECT user, host, plugin FROM mysql.user;

user	host	plugin
root	%	caching_sha2_password
root	localhost	caching_sha2_password

The story then tightened twice. Here is the state per version, each verified against the current Docker images:

Server	Default plugin	mysql_native_password status
MySQL 5.7	mysql_native_password	default
MySQL 8.0	caching_sha2_password	available
MySQL 8.4	caching_sha2_password	shipped but disabled
MySQL 9.x	caching_sha2_password	removed
MariaDB (all)	mysql_native_password (plus unix_socket for root)	default

This matters because the internet's most common advice for this error, "just switch the user back to mysql_native_password", stopped working by default in 8.4. Running it on MySQL 8.4.10 produces:

mysql> CREATE USER 'legacyapp'@'%' IDENTIFIED WITH mysql_native_password BY 'LegacyPw1!';
ERROR 1524 (HY000): Plugin 'mysql_native_password' is not loaded

MySQL 9.7 returns the same error, and the server will not even start with the --mysql-native-password=ON option that 8.4 still accepts (9.x aborts with unknown variable 'mysql-native-password=ON').

The three faces of the same problem

Depending on your stack, the failure wears different messages:

"Authentication plugin 'caching_sha2_password' cannot be loaded" means the client library predates MySQL 8.0 and has no implementation of the plugin at all. Old libmysqlclient builds, PHP before 7.4, and ancient GUI tools produce this.

"The server requested authentication method unknown to the client" is the same root cause phrased by PHP's mysqlnd and some other drivers.

"Public Key Retrieval is not allowed" comes from MySQL Connector/J. The driver understands the plugin but refuses, by default, to fetch the server's RSA public key over an insecure connection. Enabling TLS or adding allowPublicKeyRetrieval=true to the JDBC URL resolves it (the latter trades away protection against spoofing, so prefer TLS).

"Authentication requires secure connection" appears even with a current client if the channel is insecure and RSA exchange is off. Reproduced on MySQL 8.4 over plain TCP:

$ mysql -h 127.0.0.1 -u app -p --ssl-mode=DISABLED
ERROR 2061 (HY000): Authentication plugin 'caching_sha2_password' reported error:
Authentication requires secure connection.

Adding --get-server-public-key makes the same login succeed. There is one more wrinkle worth knowing: the plugin caches credentials server-side after a successful full authentication, so the insecure connection above starts working once any secure login for that user has primed the cache. If your error appears only sometimes, or only after a server restart, this cache is why.

The right fix: upgrade the client side

The durable fix is a client library from this decade, not a weaker server configuration. Minimum versions for common stacks:

• PHP: 7.4 or later. The PHP manual states caching_sha2_password is fully supported by mysqlnd as of 7.4.
• Java: Connector/J 8.x, with TLS enabled or allowPublicKeyRetrieval=true.
• C / CLI tools: any libmysqlclient or mysql client from 8.0 onward.
• Python: current releases of mysqlclient and PyMySQL both support the plugin (PyMySQL needs the cryptography package for the RSA path).
• MariaDB clients: recent MariaDB Connector/C releases speak caching_sha2_password. Testing the MariaDB 11.4 client against MySQL 8.4 succeeded, though it first failed with ERROR 2026: TLS/SSL error: self-signed certificate in certificate chain because MariaDB clients now verify server certificates by default. Against a server with a self-signed certificate you must either install a trusted certificate or pass --skip-ssl-verify-server-cert.

Desktop database clients bundle their own driver, so an outdated one fails against MySQL 8 no matter what you install system-wide. SQLPro for MySQL ships current client libraries that handle caching_sha2_password directly, and its SSH tunneling gives you a secure channel to servers that do not have TLS configured, which sidesteps the RSA requirement entirely.

The fallback, and why it is now a dead end

If you cannot upgrade a legacy client immediately, you can move individual users to the old plugin on MySQL 8.0:

ALTER USER 'legacyapp'@'%' IDENTIFIED WITH mysql_native_password BY 'a-new-password';

Caution: this changes how that account authenticates server-wide and resets its password, so every consumer of the account must be updated at the same time. Scope it to the one legacy account rather than reconfiguring the server default, and treat it as a bridge, not a destination: the same statement fails with error 1524 on 8.4 unless the server was started with --mysql-native-password=ON, and MySQL 9 removes the plugin outright. If you are creating a dedicated account for an old application anyway, our guide to creating users and granting privileges in MySQL covers the grant side.

Docker and configuration notes

On MySQL 8.0 images, the server default can be flipped at startup, which is why so many docker-compose files contain this line:

command: --default-authentication-plugin=mysql_native_password

Verified on mysql:8.0: with that flag, new users (including root) are created with mysql_native_password. On 8.4 the variable default_authentication_plugin no longer exists. Its replacement is authentication_policy, which on a stock 8.4 server reports *,, (first factor defaults to caching_sha2_password). To allow native-password accounts on 8.4 you need both --mysql-native-password=ON to load the plugin and, optionally, an authentication_policy change to make it a default. Neither option exists on 9.x.

One last cross-compatibility note: MariaDB never adopted caching_sha2_password. Its servers still default to mysql_native_password, so MySQL clients connect to MariaDB without any of this, while older MariaDB-based clients hitting a MySQL 8 server fail exactly like other legacy clients. If a connection works against MariaDB but dies against MySQL 8 with a plugin error, this default is the difference.

The MySQL manual's page on caching SHA-2 pluggable authentication documents the secure-channel rules in full, and MariaDB's authentication changes from 10.4 page covers the unix_socket side. Upgrade the client, keep caching_sha2_password on the server, and this error stays fixed through MySQL 9 instead of coming back at the next upgrade.

---