SQLSTATE[HY000] [2002] Permission denied
When you encounter SQLSTATE[HY000] [2002] Permission denied in your Laravel application, it usually indicates a network-level failure rather than a database logic error. The error code [2002] specifically corresponds to the MySQL client's inability to connect to the server. This happens before any SQL query is even attempted. If you are trying to upload a file or perform an action that requires database interaction, this error will block the operation immediately.
The core issue is almost always related to how the application server can reach the database server. It rarely means your credentials are wrong; incorrect passwords typically trigger Access denied for user. Instead, [2002] points to a blocked socket connection or a firewall configuration that prevents traffic between your web host (example.com) and your database host.
To resolve this, you must first determine the connection method defined in your .env file. Are you connecting via TCP/IP using a host address like 127.0.0.1 or an external IP, or are you relying on a Unix socket path? The troubleshooting steps differ slightly depending on the setup.
If you are connecting via TCP/IP, check the firewall rules on both the web server and the database server. A common pitfall is assuming that because your application runs on the same machine as the database, no firewall is needed. However, if the database resides on a different server or a managed cloud instance (like AWS RDS), strict security groups might be blocking port 3306. You need to ensure that the IP address of your web server is whitelisted in the database server's allowlist settings.
For local development or shared hosting environments where the app and DB are on the same machine, the issue often stems from SELinux (Security-Enhanced Linux) policies. SELinux can strictly enforce network policies that block unencrypted connections to databases unless explicitly permitted. If you see this error in a production environment, investigate whether SELinux is set to Enforcing mode. You might need to add specific booleans or rules to allow the Apache/Nginx process to communicate with the MySQL socket or port.
Another frequent cause involves the host parameter in your .env file. Developers often default to 127.0.0.1, which forces a TCP connection. If you intend to use a Unix socket, changing the host to localhost might resolve the issue if the socket path is correctly configured. However, mixing socket and TCP configurations without ensuring compatibility can lead to confusion.
When dealing with file uploads specifically, ensure that the web server user (often www-data or apache) has permission to write to the storage directory. While this error is primarily network-related, sometimes permission issues on the upload path cause the request to fail before it reaches the database layer, leading to confusion. Verify the ownership of your storage and bootstrap/cache directories.
If you are managing a multi-tier architecture where the web server and database are separated, ensure that the database user has the necessary privileges for the specific operations being performed during file uploads. Sometimes, large file uploads trigger timeouts or require specific session configurations, but these usually result in timeout errors rather than permission denied errors unless the connection itself is dropped due to firewall drops.
If you are unsure about the underlying infrastructure, consulting your hosting provider's documentation is essential. They can clarify if port 3306 is open from your IP range or if specific database connectors require additional libraries installed on the server. For instance, some older PHP versions required the pdo_mysql extension to be explicitly enabled in php.ini, though this usually results in a different error message.
By systematically checking firewall configurations, SELinux policies, and connection hostnames, you can isolate the root cause of the [2002] error. Remember that this is a connectivity issue, so focus your debugging efforts on network paths and security layers rather than application code logic.