Fix MySQL Authentication Method Unknown to the Client

The MySQL error “authentication method unknown to the client” usually means that an old application driver does not support the authentication plugin used by the MySQL account. With current MySQL, the preferred fix is to upgrade the client library or connector so it supports caching_sha2_password.

Do not immediately switch every account to mysql_native_password. It is deprecated, disabled by default in MySQL 8.4, and is not a good long-term fix.

Common error messages

The wording varies by programming language and connector:

The server requested authentication method unknown to the client
Authentication plugin 'caching_sha2_password' cannot be loaded
Client does not support authentication protocol requested by server
Authentication method unknown to the client [caching_sha2_password]

The problem can occur in PHP, Python, Java, Node.js, database tools, and older MySQL command-line clients.

Why the error happens

MySQL 8 uses caching_sha2_password as its preferred default authentication plugin. Older connectors were built before that plugin was supported. The server asks for one authentication method, but the client cannot complete it.

The error can also appear when:

• The client loads an old MySQL library at runtime.
• The application language or framework bundles an outdated connector.
• The client understands the plugin but needs TLS or RSA password exchange.
• The account uses a plugin that is disabled or missing on the server.
• A container has a different client version from the host machine.

Step 1: Check the server version

mysql --version

From an administrative MySQL session:

SELECT VERSION();

The local mysql command version and the remote server version can differ. Record both when troubleshooting.

Step 2: Check the account authentication plugin

Connect through a working administrator path:

sudo mysql

Check the exact account, including its host:

SELECT User, Host, plugin
FROM mysql.user
WHERE User = 'app_user';

'app_user'@'localhost' and 'app_user'@'10.0.20.30' are separate accounts. Make sure you inspect the one the failing connection actually matches.

Show the complete account definition:

SHOW CREATE USER 'app_user'@'10.0.20.30';

Step 3: Check the real client or connector version

Examples:

# PHP modules and runtime
php --version
php -m | grep -Ei 'mysqli|pdo_mysql'
php --ri mysqli

# Python package
python3 -m pip show mysql-connector-python

# Node.js package
npm list mysql2

# Java dependencies vary by build tool
./mvnw dependency:tree | grep -i mysql

Run these checks in the same environment as the application. A web server, PHP-FPM pool, container, virtual environment, or CI runner may load different packages from your interactive shell.

Preferred fix: upgrade the client connector

Update the application runtime and official or actively maintained MySQL connector to a version that supports caching_sha2_password. Test the update in staging before production.

Depending on the application, you may need to update:

• PHP and its mysqli or PDO_MySQL extension.
• MySQL Connector/Python.
• MySQL Connector/J for Java.
• A Node.js driver such as a maintained mysql2 release.
• The MySQL client library used by a compiled application.

Read the connector’s official compatibility notes for your MySQL server version. Do not run a blind package upgrade on a production application without a tested rollback.

Use caching_sha2_password for the account

After the client is compatible, create a new account with the server default:

CREATE USER 'app_user'@'10.0.20.30'
  IDENTIFIED BY 'replace-with-a-long-random-password';

Or set the plugin explicitly:

CREATE USER 'app_user'@'10.0.20.30'
  IDENTIFIED WITH caching_sha2_password
  BY 'replace-with-a-long-random-password';

Change an existing account:

ALTER USER 'app_user'@'10.0.20.30'
  IDENTIFIED WITH caching_sha2_password
  BY 'replace-with-a-new-random-password';

Update the application’s secret and test a new connection immediately. Changing the plugin or password can clear cached authentication information and interrupt old credentials.

Use a secure connection

caching_sha2_password requires a secure connection or supported RSA password exchange when the authentication cache cannot be used. TLS is the clearer choice for remote application traffic.

Test with encryption required:

mysql --host=db.example.internal \
  --user=app_user \
  --password \
  --ssl-mode=REQUIRED

For server identity verification:

mysql --host=db.example.internal \
  --user=app_user \
  --password \
  --ssl-mode=VERIFY_IDENTITY \
  --ssl-ca=/path/to/ca.pem

Inside the session, check the cipher:

SHOW STATUS LIKE 'Ssl_cipher';

For a full remote-access design, read our guide to allowing remote MySQL connections safely.

MySQL 8.4 and mysql_native_password

In MySQL 8.4, mysql_native_password is disabled by default. An old workaround such as this may fail:

ALTER USER 'app_user'@'localhost'
  IDENTIFIED WITH mysql_native_password BY 'password';

Even where an administrator can temporarily enable the deprecated plugin, doing so extends dependence on an authentication method scheduled for removal. Upgrade the connector and migrate accounts to caching_sha2_password.

Do not copy an old default-authentication-plugin=mysql_native_password setting into a current server configuration. MySQL authentication defaults and supported options have changed across releases.

If a legacy application cannot be upgraded immediately

Treat compatibility mode as a short, documented migration exception:

1. Confirm the exact server version and whether the legacy plugin is supported.
2. Create a separate account for only that application.
3. Restrict the account to the application host and required database.
4. Use TLS and strict firewall rules.
5. Set an owner and deadline for upgrading the connector.
6. Remove the exception after migration.

Do not downgrade every MySQL account or the global server policy to support one old application.

Grant only the required privileges

GRANT SELECT, INSERT, UPDATE, DELETE
ON app_database.*
TO 'app_user'@'10.0.20.30';

Check the result:

SHOW GRANTS FOR 'app_user'@'10.0.20.30';

Authentication plugin changes do not justify global privileges. See our guide to managing MySQL databases and users.

Test from the same application environment

A successful MySQL CLI connection does not prove that PHP, Java, Python, or Node.js loads a compatible driver. Test with the application’s real runtime, network route, account, TLS settings, and secret source.

For a web application, a small health check should avoid printing passwords, connection strings, stack traces, or database contents to the public response.

PHP-specific checks

Check the web runtime, not only CLI PHP:

php --ri mysqli
php --ri pdo_mysql

PHP-FPM may use another version or configuration. Inspect the active pool and service, then restart only after package changes have been tested:

systemctl list-units 'php*-fpm.service'
sudo systemctl restart php8.3-fpm

Replace the example service with the installed version. Do not expose a permanent phpinfo() page; it reveals sensitive environment details.

Common errors after upgrading the connector

Authentication requires secure connection

Configure TLS or the connector’s supported RSA public-key exchange. For remote traffic, require TLS and verify the server identity when possible.

Access denied for user

The plugin may now work, but the password, host match, or grants are wrong. Check:

SELECT User, Host, plugin FROM mysql.user WHERE User = 'app_user';
SHOW GRANTS FOR 'app_user'@'10.0.20.30';

Plugin mysql_native_password is not loaded

This is expected on MySQL 8.4 when the deprecated plugin is disabled. Migrate the account and upgrade the client rather than repeatedly forcing the old plugin.

The command-line client works but the website fails

The website may run in another container, virtual environment, PHP-FPM pool, user account, or network namespace. Compare the actual driver version, DNS, environment variables, TLS files, and secret values.

The application reports a public-key retrieval error

Some connectors require explicit settings for RSA public-key retrieval on an unencrypted first connection. Prefer a correctly configured TLS connection. Do not enable insecure connector flags without understanding their effect.

Migration checklist

• Back up MySQL and relevant configuration.
• Inventory account plugins and application connectors.
• Upgrade and test the client in staging.
• Configure TLS for remote connections.
• Migrate one dedicated account to caching_sha2_password.
• Update the application secret.
• Test normal jobs, workers, and scheduled tasks.
• Monitor authentication errors after deployment.
• Remove legacy-plugin exceptions.

Frequently asked questions

What is the default authentication plugin in MySQL 8.4?

caching_sha2_password is the preferred default. It uses SHA-256 authentication and a server-side cache for repeat connections.

Should I switch to mysql_native_password to fix an old PHP app?

Upgrade PHP and its MySQL client support first. The native plugin is deprecated and disabled by default in MySQL 8.4, so it is not a durable solution.

Do I need to run FLUSH PRIVILEGES after ALTER USER?

No. Account-management statements take effect immediately. Note that FLUSH PRIVILEGES also clears the caching SHA-2 authentication cache, which may affect the next connection.

Can different MySQL users use different plugins?

Yes. Authentication is configured per account, including the username and host combination. Use that flexibility for controlled migrations, not as a reason to leave old plugins indefinitely.

Official MySQL references

• MySQL 8.4 caching SHA-2 authentication
• MySQL 8.4 security FAQ
• MySQL upgrade best practices
• MySQL connection and TLS options

The correct long-term fix for an unknown MySQL authentication method is usually a compatible client connector, a caching_sha2_password account, and secure transport. Use legacy authentication only as a tightly controlled bridge with a clear removal plan.