SQLSTATE[HY000] [1698] Access denied for user 'root'@'localhost'
You've just spun up a fresh Ubuntu 16.04 LTS instance and gotten Apache or Nginx running without issue. The web server responds, but the moment you try to connect your application to MySQL, you hit a wall. The error message SQLSTATE[HY000] [1698] Access denied for user 'root'@'localhost' appears consistently in PHP and phpMyAdmin, yet logging into the MySQL terminal via SSH works perfectly fine with the same credentials.
This specific error code indicates a mismatch between how your application attempts to authenticate versus how the MySQL server is configured to accept that authentication. It is not simply a case of wrong passwords; it is a fundamental difference in protocol support based on the Ubuntu version you are running.
Ubuntu 16.04, specifically known as Xenial Xerus, ships with a patched version of MySQL Server (often referred to as Percona Server or a hardening fork of standard MariaDB) that disables the legacy authentication plugin by default for security reasons. When you log in from your terminal using mysql -u root -p, you are likely utilizing the system's shell environment which might be configured to handle the password differently, or you are connecting via TCP/IP where the client library handles the handshake automatically. However, when PHP attempts to connect using PDO, it relies on the server's active authentication plugin. If that plugin is set to caching_sha2_password (the modern standard) but your root user is still registered with the older mysql_native_password hashâor vice versaâthe connection fails immediately upon handshake, resulting in error 1698.
To resolve this without losing data or compromising security further, you need to inspect and potentially update the root user's authentication plugin configuration directly within MySQL. Since you can already access the database via the terminal, use that session to run the necessary updates.
Connect to your local instance:
mysql -u root -p
Once inside, ensure you are using root@localhost. You may need to switch to an administrative user if you encounter permission issues during the update, but typically root has full control. Run the following command to check the current authentication plugin:
SELECT User, Host, plugin FROM mysql.user WHERE User = 'root' AND Host = 'localhost';
If the output shows caching_sha2_password, this is the modern standard for MySQL 8.0+ and many hardened Ubuntu distributions. If your PHP environment or your application's logic expects the older hash format, you must switch the plugin. Execute the update command:
ALTER USER 'root'@'localhost' IDENTIFIED WITH mysql_native_password BY 'your_password';
FLUSH PRIVILEGES;
Replace your_password with the actual root password you set during installation. This forces MySQL to re-hashed your credentials using the legacy algorithm, which is compatible with older PHP PDO drivers and many third-party tools. After running this command, reload your application or clear any cached connection strings in your codebase, such as the example provided where $host is hardcoded to 127.0.0.1.
There are trade-offs to consider here. While caching_sha2_password offers improved security against offline dictionary attacks and supports stronger password policies, legacy applications or older PHP versions (like those bundled with very old LAMP stacks) might not support it out of the box. By reverting to mysql_native_password, you restore compatibility at a potential cost to future-proofing your infrastructure. If you are starting a new project on a modern stack, it is generally better to stick with caching_sha2_password and ensure your PHP version is up to date (PHP 7.4 or later) and that the MySQL client libraries support the new plugin.
If you prefer to keep the modern plugin but still face issues, verify that your PDO driver is correctly installed and that you are not inadvertently passing the wrong host. Using 127.0.0.1 instead of localhost can sometimes trigger different resolution paths in MySQL, though usually, they map to the same socket. However, mixing authentication plugins across different hosts (e.g., root@%) is a common source of confusion; ensure your application connects strictly to the host intended for local development.
For production environments where this specific error persists despite configuration changes, consider whether you need to harden the root account at all. A best practice in web application security is to avoid using the root user for database connections from your web server. Instead, create a dedicated database user with minimal privileges (e.g., CREATE, INSERT, SELECT, UPDATE, DELETE) on specific databases. This reduces the blast radius if your application layer is ever compromised and avoids the complexity of managing the superuser's authentication plugin for routine operations.
