Fix MySQL Connect Error 2054: Authentication Method Unknown

You set up MySQL 8 (or upgraded from 5.7), then a previously-working PHP, Node.js or MySQL Workbench client refuses to connect with Connect Error (2054) The server requested authentication method unknown to the client. This DevAnswers guide covers the three fixes: the recommended per-user ALTER USER, a server-wide default plugin change, and the long-term client library upgrade.

Prerequisites #

• A MySQL 8.0+ server you can log into as root (or any user with the SUPER privilege and rights to ALTER USER on the failing account).
• Root or sudo access on the host running mysqld: needed to launch sudo mysql -u root -p (if your MySQL is configured for auth_socket), for Method 2‘s server-wide config change, and for reading the MySQL error log in the Verify step.
• The username that’s failing to connect, plus knowledge of which client library is making the connection (PHP version, Node.js driver, MySQL Workbench build).
• For Method 2: a maintenance window short enough to restart mysql.service cleanly.

Why This Error Happens (MySQL 8 caching_sha2_password) #

MySQL 8.0 changed its default authentication plugin from mysql_native_password (the long-time default in MySQL 5.7 and earlier) to caching_sha2_password. The new plugin uses SHA-256 hashing with a per-connection nonce, which is more resistant to offline attacks than the SHA-1-based mysql_native_password. The caching_sha2_password documentation covers the full handshake details. Existing users keep whichever plugin they had when they were created, but every fresh CREATE USER on MySQL 8 lands them on caching_sha2_password unless you specify otherwise.

Error 2054 fires when your client library negotiates the connection’s auth handshake and only knows how to speak mysql_native_password. The server offers caching_sha2_password, the client doesn’t recognise it, the handshake fails, and the client surfaces the error as “the server requested authentication method unknown to the client”.

Method 1: ALTER USER to mysql_native_password (Per-User Fix) #

The fastest fix is to switch the specific failing user back to mysql_native_password. The blast radius is small: only that one account changes, the server stays on the modern default, and no restart is needed. Log into MySQL as root:

sudo mysql -u root -p

Confirm which plugin the failing user is currently using. The plugin column on mysql.user shows it directly:

SELECT user, host, plugin FROM mysql.user WHERE user = 'db_user';

If the plugin column shows caching_sha2_password, swap it with ALTER USER. Replace db_user, localhost, and existing_password with the actual user, host, and the password the application is currently configured with (you’re re-storing the same password under a different plugin, not setting a new one). The official ALTER USER reference covers the full syntax:

ALTER USER 'db_user'@'localhost' IDENTIFIED WITH mysql_native_password BY 'existing_password';

If you hit a different auth-denied error after this (something like 1045 or the user’s host part not matching what the application connects from), the troubleshooting paths overlap with phpMyAdmin access-denied for root@localhost and MySQL 1045 access denied with correct password.

Method 2: Change the Server-Wide Default Plugin #

If you’re managing many legacy applications and prefer not to ALTER USER each one individually, change the server’s default authentication plugin. This recipe applies to MySQL 8.0 through 8.3; on MySQL 8.4+ the default_authentication_plugin variable was removed in favour of authentication_policy, so use Method 3 (client library upgrade) instead on those releases. On 8.0-8.3, every new user created after the change gets mysql_native_password automatically. See the default_authentication_plugin server variable reference for the full set of accepted values. Existing users keep whatever plugin they were created with.

Edit MySQL’s option file. On Ubuntu and Debian the canonical path is /etc/mysql/mysql.conf.d/mysqld.cnf (the global /etc/my.cnf path also works as a top-level override on some installs):

sudo nano /etc/mysql/mysql.conf.d/mysqld.cnf

Find the [mysqld] section and add the directive:

[mysqld]
default_authentication_plugin = mysql_native_password

Save and exit (press CTRL + X, press Y, then press ENTER)

Then restart MySQL so the change takes effect:

sudo systemctl restart mysql

If the application that was failing also needs to reach MySQL over the network rather than the local socket, see Can’t connect to MySQL server remotely for the additional bind-address and skip-networking directives.

Method 3: Upgrade the Client Library (Long-Term Fix) #

Methods 1 and 2 downgrade auth to the legacy plugin. The technically correct fix is to upgrade the client library so it speaks caching_sha2_password natively. Below are the version floors for the common stacks. If you’re already on or above these, your client library isn’t the bottleneck and you can stay on caching_sha2_password:

• PHP (mysqli, PDO_MySQL): PHP 7.4 or later, with the mysqlnd driver enabled (the default on standard PHP builds).
• MySQL Connector/C (libmysqlclient): version 8.0 or later. Earlier libmysqlclient builds against MySQL 5.7 headers do not support caching_sha2.
• Node.js: use the mysql2 npm package (NOT the older mysql package). mysql2 has supported caching_sha2 since v2.0.
• Python: mysql-connector-python 8.0+ or PyMySQL 1.0+ both support caching_sha2.
• MySQL Workbench: 8.0.13 or later.

On Ubuntu and Debian, ensure PHP is current and the MySQL extension package is installed for your active PHP version. For PHP 8.3 as an example:

php -v

Note the PHP version in the output (the first line shows something like PHP 8.3.x). Then install the matching php{VER}-mysql package; the example below targets PHP 8.3:

sudo apt update
sudo apt install php8.3-mysql

Then restart whatever process pools the database connection (Apache, PHP-FPM, your app server) so it reloads the updated extension.

Verify the Fix #

After applying Method 1, re-check the user’s plugin column to confirm the change landed:

SELECT user, host, plugin FROM mysql.user WHERE user = 'db_user';

The plugin column should now read mysql_native_password. Then reconnect from the application that was failing. If you still see error 2054, the client is using a stale connection from the pool. Restart the application server or wait for the pool to recycle. If you see a different error (1045, host-mismatch, or set-password has no significance), the auth plugin is now correct but you have a separate credentials or host-binding issue. If MySQL’s error log gives more detail, the defensive log lookup is:

sudo tail -n 30 /var/log/mysql/error.log 2>/dev/null || sudo journalctl -u mysql --no-pager -n 30

Conclusion #

Error 2054 is a compatibility hurdle, not a security failure. MySQL 8’s caching_sha2_password default is the safer plugin; mysql_native_password uses the older SHA-1-based hashing. Method 1 (ALTER USER) and Method 2 (server-wide default) are tactical fallbacks that let legacy clients keep working. Method 3 (upgrade the client library) is the long-term answer, especially because Oracle has signalled mysql_native_password for deprecation in future MySQL major releases. With a working connection in place, the next reasonable step is a clean MySQL backup workflow so you have a safety net before any further auth changes.