PDOException SQLSTATE[HY000] [2002] No such file or directory

PDOException SQLSTATE[HY000] [2002] No such file or directory

  1. Blog
  2. 15 November 2026
  3. 3 min read

Stefan Bogdanescu

Founder & Senior Architect

PDOException SQLSTATE[HY000] [2002] No such file or directory

When you deploy a Laravel application to a shared hosting environment like Fortrabbit, the transition from local development to production often reveals infrastructure gaps that are invisible on your machine. You might successfully access the site via HTTP, serving static assets and rendered views without issue. However, as soon as you connect via SSH and attempt to run database-related commands—such as php artisan migrate or php artisan db:seed—you may encounter a cryptic error message:

[PDOException] SQLSTATE[HY000] [2002] No such file or directory

This specific error code, SQLSTATE[HY000] [2002], indicates a failure at the connection layer. It does not mean your database tables are missing; in fact, as you noted, the migrations likely ran previously, and the schema exists. The error explicitly states that the client cannot establish a socket connection to the server where the database resides. In the context of Laravel's PDO driver, this usually means the application is trying to reach a Unix socket file at a path that no longer exists or has incorrect permissions.

On local development setups using MySQL or MariaDB, it is common to use Unix sockets for inter-process communication. These are special files in the filesystem (e.g., /var/run/mysqld/mysqld.sock) that allow applications to talk to the database engine without opening a TCP/IP port. When you switch environments, particularly when deploying to a platform like Fortrabbit where the database might be managed by an external service or running on a different host than your web server, the configuration for these sockets often needs to change.

The root cause of this error in a production deployment scenario is almost invariably the DB_HOST configuration. If your .env file still references 127.0.0.1 or relies on a socket path like /var/run/mysqld/mysqld.sock, but your application server cannot reach that specific location, PDO throws this exception. Even if the database is accessible via TCP/IP (port 3306), the application is attempting to dial into a non-existent file-based socket.

To resolve this, you must inspect your .env file on the deployed instance. Look specifically at the DB_HOST, DB_PORT, and DB_SOCKET variables. If you are connecting to an external managed database or a separate container, the DB_HOST should typically be set to the hostname provided by your hoster (e.g., db.fortrabbit.app) rather than 127.0.0.1. Furthermore, ensure that the DB_SOCKET variable is cleared or commented out if you are not explicitly using a Unix socket connection in that environment.

Sometimes, the issue persists even after correcting the host settings due to caching or lingering configuration artifacts. Running php artisan config:clear and php artisan cache:clear via SSH can help reset any cached configuration that might be holding onto old connection parameters. Additionally, verify that your database credentials (username and password) are correct for the new environment, as authentication failures can occasionally manifest similarly if the connection attempt itself fails silently before returning a specific error code.

If you are unsure about the database structure or whether migrations actually ran on the production instance, it is prudent to check the database directly via the hoster's dashboard or a dedicated database client tool provided by Fortrabbit. You can inspect the information_schema tables to confirm that the expected tables exist and that no partial migration states are causing conflicts.

For developers looking for deeper insights into configuring Laravel for various hosting environments, including best practices for environment variables and database management, resources like https://laravelcompany.com offer comprehensive guides on scaling and securing your application infrastructure. Understanding the distinction between local socket connections and remote TCP/IP connections is fundamental to ensuring your database layer remains stable across different deployment targets.

Our network