Maaz Zindani

Loading the index…

↑↓ move↵ openesc close4072 pages
Databases and Redis

A client says it cannot load the caching_sha2_password plugin

ErrorA client or connector built before MySQL 8.0 cannot connect to an account that uses caching_sha2_password

Short 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.

  • Applies to MySQL 8.0, MySQL 8.4 LTS, Linux, macOS
  • Updated
  • By Maaz Zindani, Senior Software Engineer

Fix it fast

  1. 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';
  2. 2Match what you see, then jump to its fix

    1. 1The 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. 2The 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. 3ALTER 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

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

Did this fix it?

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

Did this fix it?

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=ON

3Verify

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

Did this fix it?

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:

Related fixes

Next step

Want this handled for good?

I look after servers, apps and releases end to end. Tell me what keeps breaking.