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

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

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

Stefan Bogdanescu

Founder & Senior Architect

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

When running php artisan migrate on OS X with MySQL installed via Homebrew, you might encounter the error SQLSTATE[HY000] [2002] No such file or directory. While many online resources suggest this indicates a communication breakdown between PHP and MySQL, the root cause is often more specific: a mismatch in socket paths.

This error occurs when Laravel's PDO driver attempts to connect to the database using a socket path that does not exist or does not match the one MySQL is actually listening on. Even if you have configured your php.ini file and your MySQL configuration (my.cnf) with the same socket path (e.g., /tmp/mysql.sock), the connection will fail if the PHP process running Laravel cannot access that specific file, or if the paths are inconsistent across different components of the stack.

On OS X systems using Homebrew, MySQL typically defaults to listening on a Unix socket located at /tmp/mysql.sock. However, there are two critical areas where configuration can diverge: the PHP build-time settings and the runtime environment variables. If your PHP installation was compiled with --with-mysql-sock=/tmp/mysql.sock but your application runs in an environment where that socket is missing or inaccessible, the error persists.

One common pitfall involves managing multiple versions of PHP on a single machine. If you installed additional packages like mcrypt or other legacy extensions, they might have pulled in a different version of PHP with its own configuration file. When you run phpinfo(), ensure you are inspecting the correct configuration directory. In the example provided, the user pointed to /usr/local/etc/php/5.4/php.ini. If your Homebrew installation uses a different PHP path (such as one under /usr/local/bin/php), you must ensure that the pdo_mysql.default_socket, mysqli.default_socket, and mysql.default_socket directives in the active configuration file are explicitly set to match MySQL's socket location.

# /path/to/your/active/php.ini
pdo_mysql.default_socket=/tmp/mysql.sock
mysqli.default_socket = /tmp/mysql.sock
mysql.default_socket = /tmp/mysql.sock

Additionally, verify that your MySQL instance is actually creating the socket file at the configured location. In /usr/local/Cellar/mysql/5.6.16/my.cnf, setting socket = /tmp/mysql.sock tells MySQL where to write the socket. However, if MySQL is running as a daemon with restricted permissions, it might fail to create the file in /tmp if the directory lacks write permissions for the MySQL user.

Sometimes, simply restarting Apache or the web server isn't enough because the PHP-FPM service or CLI binary used by Artisan might be pointing to a different installation entirely. To diagnose this, run php -r "echo ini_get('extension_dir');". If you are using a global installation of Homebrew PHP but your project expects a specific version managed by virtualenv or Docker, the socket paths will never align.

A more robust solution in modern Laravel deployments is to avoid relying on Unix sockets altogether when using CLI tools or containerized environments. Instead, configure MySQL to listen on TCP/IP (e.g., bind-address = 0.0.0.0) and ensure both PHP and MySQL can communicate over port 3306. This removes the dependency on socket file existence and permissions, which are frequent sources of the "No such file or directory" error.

If you must stick to sockets, ensure that the pdo_mysql driver is using the native MySQL driver (mysqlnd) rather than the older libmysqlclient, as mysqlnd handles connection parameters slightly differently depending on the OS X version and PHP build. Finally, always check that the socket file exists before attempting migration:

ls -l /tmp/mysql.sock

If the file is missing, restart MySQL with the correct configuration or switch to TCP connections to bypass the socket dependency entirely.

Our network