TL;DR: The Quick FixHit a wall with a connection error? If you need your app back online immediately, run this SQL command in your MySQL terminal to bypass the protocol mismatch:
ALTER USER 'your_username'@'localhost' IDENTIFIED WITH mysql_native_password BY 'your_password';
FLUSH PRIVILEGES;
Swap your_username and your_password with your actual credentials. This command reverts the user's authentication to the legacy format that almost every client supports.
Why This HappensMySQL 8.0 changed the rules. It swapped the default authentication method from mysql_native_password to caching_sha2_password to beef up security and performance. While it is a better standard, older drivers simply don't speak the new language.
The ER_NOT_SUPPORTED_AUTH_MODE error triggers when a client—like the legacy Node.js mysql package (v2.18.1 and below) or PHP versions older than 7.2.4—tries to connect. The client expects a traditional handshake. Instead, the server sends a SHA256-based challenge that the client doesn't know how to solve. The connection dies right there.
Fix Approach 1: Target Specific UsersThe most precise solution is to change the plugin for only the specific account your application uses. This avoids weakening security for the entire server. Best of all? No restart required.
- Access your MySQL shell:
mysql -u root -p- Update the user. If your user is 'web_app' connecting from any host ('%'):ALTER USER 'web_app'@'%' IDENTIFIED WITH mysql_native_password BY 'StrongPassword123!';- Commit the change:``` FLUSH PRIVILEGES;
### A Note on Credential SecurityLegacy authentication is less robust than the new SHA2 default, so password strength matters more than ever. Avoid simple strings. Use a tool like the [ToolCraft Password Generator](https://toolcraft.app/en/tools/security/password-generator) to build high-entropy keys. It generates secure strings locally in your browser, keeping your credentials off the network during the creation process.
## Fix Approach 2: Change Global DefaultsManaging dozens of users? You can force MySQL to use the legacy plugin for every **new** user created from now on. Keep in mind that this won't automatically fix users that already exist; you still have to `ALTER` those manually.
- Open your config file (`my.cnf` on Linux/macOS or `my.ini` on Windows).- Under the `[mysqld]` header, add this line:```
[mysqld]
default_authentication_plugin=mysql_native_password
```- Restart the service to apply:```
# Ubuntu/Debian
sudo systemctl restart mysql
# macOS (Homebrew)
brew services restart mysql
VerificationCheck your work by querying the user table. It shows exactly which plugin each account is using:
SELECT user, host, plugin FROM mysql.user;
Look for mysql_native_password in the results. If it still shows caching_sha2_password, double-check that the host in your ALTER USER command matches exactly (e.g., 'root'@'localhost' is different from 'root'@'%').