Setting up Laravel on a Mac php artisan migrate error: No such file or directory

Setting up Laravel on a Mac php artisan migrate error: No such file or directory

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

Stefan Bogdanescu

Founder & Senior Architect

Setting up Laravel on a Mac: Resolving "No such file or directory" Errors During Migration

Migrating a perfectly functional Laravel project from Linux to a macOS environment often triggers unexpected connectivity issues, particularly when running php artisan migrate. This specific error—SQLSTATE[HY000] [2002] No such file or directory—is not always indicative of a missing database server. Instead, it frequently points to a socket path mismatch between the PHP process and the MySQL service.

When you pull a project into MAMP (or XAMPP) on macOS, the database server typically runs as a local daemon that communicates via Unix domain sockets rather than TCP/IP. The default configuration in config/database.php often attempts to connect using 'host' => 'localhost'. In many PHP environments, including those running under Apache or CLI tools like MAMP, this setting instructs the driver to look for a TCP connection on port 3306. However, if MySQL is configured to listen only on the socket file (which is common in local development stacks), the PHP PDO driver cannot find the expected network endpoint, resulting in the "No such file or directory" exception.

A critical detail often overlooked involves the version of PHP and the specific environment running it. In the scenario described, php -v reported version 5.5. This version predates the widespread adoption of MySQL's TCP/IP listener by default in local development tools. While swapping 'localhost' for '127.0.0.1' forces a TCP connection, this approach fails if the MySQL service itself is not explicitly configured to accept remote connections on port 3306. The error persists because the underlying socket file remains unreachable or non-existent at the expected path.

The initial attempt to resolve this involves modifying php.ini. Adding lines such as:

mysql.default_socket = /var/run/mysqld/mysqld.sock
mysqli.default_socket = /var/run/mysqld/mysqld.sock
pdo_mysql.default_socket = /var/run/mysqld/mysqld.sock

aims to force the PHP driver to use a specific socket. However, this solution is fragile on macOS because the physical location of the socket file varies by installation. MAMP often installs MySQL in /Applications/MAMP/var/mysql, whereas XAMPP places it in /Applications/XAMPP/xamppfiles/var/mysql. Hardcoding a path like /var/run/mysqld/mysqld.sock often fails on macOS unless that directory is explicitly created and linked, which adds unnecessary complexity.

A more robust approach involves checking where the actual socket file resides. You can locate it by inspecting the MAMP configuration or running mysql_config --socket. Once identified, you must ensure your php.ini references the correct absolute path, or better yet, switch the database driver to use TCP/IP explicitly if the network stack is available. This is done by updating config/database.php:

'mysql' => array(
    'driver'    => 'mysql',
    'host'      => '127.0.0.1', // Force TCP connection
    'port'      => 3306,       // Ensure port is specified
    'database'  => 'essays',
    'username'  => 'root',
    'password'  => 'root',
    'charset'   => 'utf8',
),

By explicitly setting the host to 127.0.0.1 and including a port, you bypass the socket lookup entirely, provided the MySQL service is listening on that interface. If the MAMP environment restricts network access for security reasons, ensure the "Start MySQL" option is active in the dashboard before running migrations.

For developers working with legacy PHP versions like 5.5 found in older macOS setups or virtual machines, reliance on socket configuration is often necessary due to deprecated TCP support. In such cases, manually creating a symlink as attempted in the source material—sudo ln -s /Applications/XAMPP/xamppfiles/var/mysql/mysql.sock /var/run/mysqld/mysqld.sock—can work, but it requires sudo permissions and careful handling of file ownership to prevent permission denied errors during the migration process.

When troubleshooting these issues, always verify that the MySQL service is actually running via Activity Monitor or the MAMP dashboard before executing artisan commands. The error message can be misleading; it suggests a file system issue when the root cause is often a configuration mismatch between the PHP driver and the database daemon's listening protocol.

Our network