A client says it cannot load the caching_sha2_password plugin
A client or connector built before MySQL 8.0 cannot connect to an account that uses caching_sha2_passwordShort answer
MySQL 8 and 8.4 create accounts with the caching_sha2_password plugin. A client built on an older client library does not have that plugin, so login fails. Update the client or driver first. If you cannot, switch only that account to mysql_native_password with ALTER USER. In 8.4 you must also turn that plugin on in the server config.
Fix it fast
1Find out which cause you have
Ask the server which plugin the failing account uses, and which plugins are loaded.
SELECT user, host, plugin FROM mysql.user WHERE user = 'app_user'; SELECT PLUGIN_NAME, PLUGIN_STATUS FROM INFORMATION_SCHEMA.PLUGINS WHERE PLUGIN_NAME LIKE '%sha2%' OR PLUGIN_NAME = 'mysql_native_password';2Match what you see, then jump to its fix
- 1
The same account logs in fine from the mysql command line on the server, but fails from an old GUI tool, driver or app.The client or driver is older than MySQL 8Fix - 2
The plugin column in mysql.user shows caching_sha2_password for the account the old tool uses.The tool cannot be updated, so one account must use mysql_native_passwordFix - 3
ALTER USER ... mysql_native_password fails, or the plugin does not appear as ACTIVE in INFORMATION_SCHEMA.PLUGINS.MySQL 8.4 or later has mysql_native_password switched offFix
- 1
What does the error look like?
A client or connector built before MySQL 8.0 cannot connect to an account that uses caching_sha2_password
Cause 1 of 3
The client or driver is older than MySQL 8
1Check
The MySQL manual says the client side of caching_sha2_password is built into libmysqlclient, and that clients and connectors not updated to know about it cannot connect to accounts that use it. Compare the client version with the server.
mysql --version
mysql -u app_user -p -e "SELECT VERSION();"2Fix
Relink the client against libmysqlclient from MySQL 8.0 or higher, or get an updated connector or GUI tool that recognizes caching_sha2_password, as the manual advises. This keeps the stronger default plugin.
# Update the tool (Workbench, Navicat, your language driver) to a current release, then reconnect.3Verify
Log in again from the tool that failed.
SELECT CURRENT_USER(), @@version;Confirmed by dev.mysql.com
Cause 2 of 3
The tool cannot be updated, so one account must use mysql_native_password
1Check
Confirm the account name and host from the first step. Change only the accounts that old tools need, not every user.
SELECT user, host, plugin FROM mysql.user;2Fix
Change the account with ALTER USER and set the password again. On 8.0 this works at once.
ALTER USER 'app_user'@'localhost'
IDENTIFIED WITH mysql_native_password BY 'a-long-new-password';3Verify
The plugin column now shows mysql_native_password.
SELECT user, host, plugin FROM mysql.user WHERE user = 'app_user';Confirmed by dev.mysql.com
Cause 3 of 3
MySQL 8.4 or later has mysql_native_password switched off
1Check
MySQL 8.4 disables mysql_native_password by default, and MySQL 9.0 removes it. In 9.0 or later this cause cannot be fixed: update the client instead.
SELECT PLUGIN_NAME, PLUGIN_STATUS FROM INFORMATION_SCHEMA.PLUGINS WHERE PLUGIN_NAME = 'mysql_native_password';2Fix
On 8.4 only, enable the plugin in the server option file under [mysqld], restart the server, then run the ALTER USER from the cause above.
# /etc/mysql/my.cnf or the option file your install reads
[mysqld]
mysql_native_password=ON3Verify
After the restart the plugin shows as ACTIVE.
SELECT PLUGIN_NAME, PLUGIN_STATUS FROM INFORMATION_SCHEMA.PLUGINS WHERE PLUGIN_NAME = 'mysql_native_password';Confirmed by dev.mysql.com
How do I stop it coming back?
- Keep GUI tools and language drivers on current releases before you upgrade the server.
- Test a login from every client you use against a staging server before moving to MySQL 8.4.
- Treat mysql_native_password as a short-term bridge: it is deprecated and gone in MySQL 9.0.
- Change the plugin per account, not as a server-wide default.
Sources
How was this page made?
I drafted this page with AI assistance from the official documents listed under Sources. Every cause above names the document that confirms it. I have not reproduced this fix on a machine of my own yet, so read it as documented guidance, not a test report. Found a mistake? Tell me.
Which stack is behind this page?
Projects of mine built on the same technologies:
- TaxiDexMy own multi-tenant taxi dispatch SaaS: API, dispatcher portal, driver and passenger apps, and the servers underneath.
- QistLockA NestJS and React SaaS driving an Android Device Owner agent that locks financed phones when payments lapse.
- ShopGoAn e-commerce aggregator with a Python scraping engine behind its catalog, past 10K Google Play downloads.
Related fixes
Databases
Installing the Airflow MySQL provider fails on pkg-config or mysqlclient
Building the mysqlclient wheel fails during the install
The Airflow MySQL provider depends on mysqlclient, which pip compiles against the MySQL C client library.
2 causes, each with a fixDatabases
Compiling a C or C++ program that includes mysql.h fails
undefined reference to `mysql_init'
The compiler only finds mysql.h when the MySQL client development files are installed and their folder is on the include path.
3 causes, each with a fixDatabases
An EC2 instance cannot reach its RDS database
Could not open connection to the host, on port <port>: Connect failed
RDS denies all access until a security group allows it.
3 causes, each with a fixDatabases
Locked out of a fresh MariaDB install as root on Mac or Linux
ERROR 1045 (28000): Access denied for user 'root'@'localhost' (using password: NO)
A fresh MariaDB root account is not a normal password account.
3 causes, each with a fixDatabases
An Aria table fails with 'Read page with wrong checksum' (error 1030, code 176)
ERROR 1030 (HY000): Got error 176 "Read page with wrong checksum" from storage engine Aria
Code 176 means MariaDB's Aria engine read a data or index page whose checksum does not match, so that table file is damaged.
3 causes, each with a fixDatabases
The client cannot open a TCP connection to MariaDB or MySQL (error 2003)
ERROR 2003 (HY000): Can't connect to MySQL server on '127.0.0.1:3306' (111)
Error 2003 means the client tried a TCP connection to the host and port and nobody answered.
4 causes, each with a fix