Introduction

This MySQLi error appears when the MySQL server expects the caching_sha2_password authentication plugin, but the PHP client stack does not understand it. The usual situation is a newer MySQL server combined with an older PHP or MySQL client library.

Why the Error Appears

MySQL 8 made caching_sha2_password the default authentication plugin for new users. Older PHP environments, especially older MySQLi or mysqlnd stacks, may not support that plugin correctly. When the client connects, authentication fails before the application can do anything useful.

So the real compatibility boundary is not only PHP code. It is the combination of PHP version, MySQL client library, and server authentication plugin.

Preferred Fix: Upgrade the PHP Client Stack

The best long-term fix is usually to upgrade PHP and the relevant MySQL client components so the application can speak the server’s default authentication method correctly.

That keeps the stronger server-side default in place and avoids weakening authentication only to satisfy an outdated client.

Compatibility Workaround: Change the MySQL User Plugin

If upgrading the client stack is not immediately possible, a common workaround is to alter the affected MySQL user to use mysql_native_password instead.

ALTER USER 'appuser'@'localhost'
IDENTIFIED WITH mysql_native_password BY 'strong-password';
FLUSH PRIVILEGES;

This can restore connectivity for older PHP applications, but it should be treated as a compatibility measure, not the preferred architectural end state.

Check What the User Is Configured To Use

You can inspect the user’s authentication plugin directly.

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

That helps confirm whether the server is actually using caching_sha2_password for the account your application is trying to use.

Think About Security Before Choosing the Workaround

Changing users back to mysql_native_password may be operationally convenient, but it reduces alignment with newer MySQL defaults. If the application is important and maintained, upgrading the PHP runtime or client stack is usually the cleaner fix.

A good rule is:

• upgrade the client if you can,
• fall back to plugin downgrade only when compatibility pressure leaves no short-term alternative.

Test the Specific Application User, Not Only the Server

This issue is user-specific because the authentication plugin is attached to the MySQL account. One application may fail while another still connects successfully if the accounts use different plugins. Always check the exact user your PHP application is using rather than assuming every MySQL account on the server behaves the same way.

Common Pitfalls

• Treating the issue as a PHP syntax problem instead of a client-server authentication mismatch.
• Downgrading the server user plugin without planning a later client upgrade.
• Forgetting to inspect which authentication plugin the MySQL user actually uses.
• Upgrading MySQL server versions without checking PHP client compatibility in advance.
• Applying the workaround broadly instead of limiting it to the specific affected accounts.

Summary

• The error means the PHP MySQL client does not support the server user’s caching_sha2_password authentication method.
• MySQL 8 defaults often expose this issue when older PHP stacks connect.
• Upgrading PHP and the client library is usually the preferred fix.
• Changing the user to mysql_native_password is a common compatibility workaround.
• The right solution is a client-server compatibility decision, not only a code change.
• Prefer stronger modern compatibility over permanent auth downgrades when possible.
• Compatibility workarounds should be tracked and removed once the client stack is fully upgraded safely.