Diagnosing "No such file or directory" and Host Resolution Errors in Laravel Migrations
When you delete the migrations table from your Laravel database and attempt to run php artisan migrate:install, you might encounter a confusing stack trace indicating a connection failure rather than a missing table. The error message often reads as SQLSTATE[HY000] [2002] No such file or directory. While the SQL query itself is attempting to check the information_schema.tables, the underlying PHP process cannot even reach the database server, making it impossible for Laravel to execute the query successfully.
This issue is not related to the table's existence or your Composer dependencies. It points directly to a misconfigured connection environment. The error code [2002] in MySQL is specific; it indicates that the client application could not establish a socket or TCP/IP connection to the database server at all. When you manually create the migrations table via phpMyAdmin, the operation succeeds because the web server's PHP process can resolve the host and connect there. However, when running artisan commands from your terminal (CLI), the environment variables are often different.
The most frequent culprit for this behavior is a mismatch between your .env file settings and your actual database configuration. If your DB_HOST is set to 127.0.0.1 but your MySQL server expects connections on a Unix socket, or vice versa, the CLI environment might not be picking up the correct path. Furthermore, if you are running Laravel in a containerized environment like Docker Compose, the host resolution can fail entirely if the application container cannot route traffic to the database service defined in docker-compose.yml.
Consider the scenario where your .env file specifies DB_HOST=127.0.0.1. In a standard Linux installation, MySQL often listens on a Unix socket (e.g., /var/run/mysqld/mysqld.sock) rather than TCP/IP by default. If your PHP CLI environment is configured to use the TCP socket but the MySQL server isn't listening on port 3306 for TCP connections, or if the socket path is missing from the php.ini configuration, you will hit the "No such file or directory" error. The PHP function socket_connect fails because the target endpoint doesn't exist in the network namespace of your CLI process.
Similarly, errors like php_network_getaddresses: getaddrinfo failed: No such host is known suggest a DNS resolution failure. This often happens when you are running the CLI commands on a machine that does not have valid DNS entries for the database hostname defined in your .env file. If you changed your database host from localhost to a custom domain or an IP address, ensure that this change is reflected in both your web server configuration (via config/database.php) and your local terminal environment.
Another common pitfall involves port conflicts or incorrect port numbers. If your MySQL server is running on port 3307 but your .env file specifies 3306, the connection attempt will fail with a host resolution error because the system cannot find the service listening on the requested address and port combination. Always verify that DB_PORT matches the actual listener port of your database instance.
If you are developing locally using WAMP, XAMPP, or MAMP, these environments often rely on local socket connections. Ensure that your PHP CLI is configured with the correct pdo_mysql.default_socket directive if you intend to use sockets instead of TCP. Conversely, if you need TCP connections, ensure that the MySQL server is bound to 0.0.0.0 or specifically to 127.0.0.1.
In some cases, particularly when moving from a development environment to production, the database credentials or hostnames might be cached in an old .env file or autoloaded configuration that overrides your current settings. Clearing your application cache with php artisan config:clear and ensuring your composer.json dependencies are up to date can help rule out stale configuration artifacts.
For complex setups involving multiple databases or read replicas, ensure that the specific connection being queried by migrate:install matches the primary database schema. Sometimes, a typo in the .env file for the DB_DATABASE name can cause the driver to fail if it attempts to query a non-existent schema, though this usually results in an "Unknown database" error rather than a host resolution error.
If you are using Docker and encountering these errors, inspect the network mode. If your containers are not on the same network bridge, they cannot resolve each other's hostnames. Adding the correct network_mode: host or ensuring proper DNS names in docker-compose.yml is essential for service discovery between the web container and the database container.
Ultimately, these errors are connectivity issues masquerading as database schema problems. By checking your .env variables, verifying socket vs. TCP configurations, and ensuring your PHP CLI environment matches your MySQL server's listening modes, you can resolve the "No such file or directory" and host resolution failures effectively.
