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. 4 min read

Stefan Bogdanescu

Founder & Senior Architect

Decoding the SQLSTATE[HY000] [2002] Error in Local Development

Encountering a PDOException with the message SQLSTATE[HY000] [2002] No such file or directory during local development is a classic symptom of environment misconfiguration. This specific error code does not indicate a failure within the SQL logic or the database schema itself; rather, it points to a fundamental breakdown in network communication between your PHP application and the MySQL server.

When you attempt to instantiate a PDO object with the DSN string mysql:host=localhost, the driver interprets "localhost" as a directive to connect via the Unix socket file system or the TCP loopback interface (127.0.0.1). The error message explicitly states that the requested resource could not be found. In the context of PHP and MySQL, this almost invariably means the process cannot locate the mysql.sock file required for inter-process communication on your operating system.

The stack trace provided in your scenario highlights the failure occurring at line 17 within /Applications/MAMP/htdocs/PushChatServer/api/test/database.php. This confirms that the application is attempting to establish a connection immediately upon loading, failing before any query execution. The root cause is rarely that MySQL is down; it is almost always that the path to the socket file defined in your PHP configuration does not match the actual location where MAMP has spawned its MySQL instance.

Understanding the Socket vs. Port Discrepancy

MySQL servers listen on a port (typically 3306) and a specific socket file path. On a Linux or macOS system, these are distinct endpoints. The localhost keyword tells PHP to try connecting via the socket first. If that fails, it falls back to TCP/IP. However, if the socket file path is missing or incorrect, the connection attempt throws the "No such file or directory" exception immediately.

In environments like MAMP, which bundle MySQL with Apache/Nginx and PHP in a single application suite, the default socket location is often /tmp/mysql.sock. If your php.ini file—specifically the one active for your MAMP virtual host—is configured to look for the socket at /var/run/mysqld/mysqld.sock, but MAMP actually places it in /tmp, the connection will fail.

To resolve this, you must inspect where the socket actually exists. Run the following command in your terminal within the MAMP directory:

ls -la /Applications/MAMP/Library/mysql-sock-files/
# or check common locations depending on your OS version
ls -la /tmp/mysql.sock

If the file exists but PHP cannot see it, you need to update your php.ini configuration. Locate the line starting with default_socket_path. It often looks like this:

default_socket_path = /var/run/mysqld/mysqld.sock

You must change this path to match where MAMP is actually running its socket, typically /Applications/MAMP/tmp/mysql/mysql.sock or simply /tmp/mysql.sock. After modifying the configuration, ensure you restart the MAMP server for the changes to take effect.

Hardcoding the Connection String as a Fallback

While fixing the default_socket_path is the "correct" architectural approach, it can be tedious during rapid local development. A pragmatic alternative that many engineers adopt is to bypass the socket entirely and force a TCP/IP connection. This removes any dependency on the specific socket file path and relies solely on the port number (usually 3306).

You can achieve this by modifying your PDO instantiation code in database.php. Instead of using mysql:host=localhost, explicitly specify the host as 127.0.0.1:

$dsn = 'mysql:host=127.0.0.1;port=3306;charset=utf8';
$username = 'root';
$password = ''; // Ensure this matches your MAMP config
$options = [
    PDO::ATTR_ERRMODE            => PDO::ERRMODE_EXCEPTION,
    PDO::ATTR_DEFAULT_FETCH_MODE => PDO::FETCH_ASSOC,
];

try {
    $pdo = new PDO($dsn, $username, $password, $options);
} catch (PDOException $e) {
    echo 'Connection failed: ' . $e->getMessage();
}

By using 127.0.0.1, you bypass the socket file lookup mechanism entirely. The PHP runtime will attempt to connect directly to the MySQL service listening on port 3306 via TCP. If MAMP is configured correctly, this connection should succeed even if the socket path in php.ini is wrong. This method is particularly useful when migrating codebases or when switching between different local environments where socket paths vary.

Verification and Next Steps

Once you have either corrected the default_socket_path or switched to the TCP host specification, verify that the database connection works by running a simple query:

$stmt = $pdo->query("SELECT 1");
$result = $stmt->fetch();
echo "Connection successful.";

If this executes without throwing an exception, your local development environment is ready for the next phase of your PushChatServer implementation. Remember that while localhost is convenient, it introduces a layer of complexity regarding socket paths on Unix-like systems. Explicitly defining the host or correcting the PHP configuration ensures stability and reduces debugging time when issues arise.

Our network