Decoding Access Denied Errors in MySQL Connections
The error message Connection failed: Access denied for user 'username'@'localhost' (using password: YES) is one of the most frequent stumbling blocks for PHP developers. It appears deceptively simple, yet it often leads to hours of debugging because the solution requires understanding how MySQL handles authentication differently than standard file permissions. The core issue isn't that your database doesn't exist or that your code has a syntax error; it is strictly an identity verification failure within the MySQL server itself.
When you attempt to connect using mysqli_connect, the PHP client sends credentials to the MySQL server. If the server rejects them, it returns this specific error. The most common misconception is assuming that creating a user and granting privileges in phpMyAdmin or via SQL commands is sufficient. However, as seen in many troubleshooting threads, simply running GRANT ALL PRIVILEGES ON *.* TO 'username'@'localhost'; followed by FLUSH PRIVILEGES; does not always resolve the issue if the authentication plugin configuration has changed.
The Authentiication Plugin Mismatch
One of the primary reasons this error persists despite correct SQL syntax is a mismatch between the authentication plugin stored in your user table and the one your application expects or supports. Modern versions of MySQL (5.7+) and MariaDB default to caching_sha2_password for new users, while older PHP installations (running on MySQL 5.6 or earlier) might only support mysql_native_password.
If your username was created as a new user in a modern MySQL environment, it likely uses caching_sha2_password. If you are running an older version of PHP that doesn't have the necessary SSL libraries or updated drivers to handle this handshake, or if you haven't explicitly changed the plugin, the connection will fail even with the correct password.
To fix this without upgrading your PHP stack, you can force the user to use the legacy algorithm:
ALTER USER 'username'@'localhost' IDENTIFIED WITH mysql_native_password BY 'password';
FLUSH PRIVILEGES;
This command explicitly tells MySQL to store and verify the password using the older mysql_native_password method. This is a critical step if you are maintaining legacy applications or running on constrained hosting environments where upgrading PHP versions isn't immediately possible.
Verifying Hostname Matching
Another frequent oversight involves the host field in the user table. The error specifically mentions 'username'@'localhost'. If your application code defines $servername as "localhost", MySQL expects the user to be defined exactly for that host string.
If you created the user using username@% or if there is a discrepancy between how PHP resolves the server name (which can sometimes resolve to 127.0.0.1) and how MySQL stores the user, the connection will fail. While localhost usually refers to socket connections and 127.0.0.1 refers to TCP/IP, MySQL treats these as distinct authentication identities. If your code connects via a Unix socket but the user is only defined for IP addresses, or vice versa, you will see this error.
To verify your current users and their host definitions, run:
SELECT User, Host, plugin FROM mysql.user WHERE User = 'username';
Ensure that there is an entry specifically for 'username'@'localhost' with a compatible plugin. If only 'username'@'%' exists, you may need to create the specific localhost user:
CREATE USER 'username'@'localhost' IDENTIFIED BY 'password';
GRANT ALL PRIVILEGES ON databasename.* TO 'username'@'localhost';
FLUSH PRIVILEGES;
Handling SSL and Encryption
In some hosting environments, particularly those running MySQL 8.0 or later, the server may enforce SSL for connections from specific hosts. If your PHP client does not have an SSL certificate configured or if the connection string doesn't request it, the authentication handshake can fail before the password is even checked, sometimes manifesting as an access denied error depending on the MySQL version's strictness.
If you are using a framework like Laravel, ensure that your .env file doesn't enforce SSL requirements that your local environment cannot meet unless you have configured the necessary certificates. For raw PHP connections, adding mysqli_options(MYSQLI_INIT_COMMAND, "SET GLOBAL sql_mode=(SELECT CONCAT(@@sql_mode,',STRICT_TRANS_TABLES'))") is generally not required for this specific error, but ensuring your connection options are clean is always advisable.
For more complex deployment scenarios involving shared hosting or containerized databases, resources like https://laravelcompany.com often provide detailed guides on configuring environment variables to match the database server's security requirements without breaking legacy authentication methods.
Ultimately, resolving this error requires aligning three things: the MySQL server version, the PHP driver capabilities, and the specific user definition in the mysql.user table. Ignoring any one of these will result in the same frustrating access denied message.