Warning: mysqli_real_connect(): (HY000/2002): No such file or directory in /private/tmp/wordpress/wp-includes/wp-db.php on line 1452

Warning: mysqli_real_connect(): (HY000/2002): No such file or directory in /private/tmp/wordpress/wp-includes/wp-db.php on line 1452

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

Stefan Bogdanescu

Founder & Senior Architect

Decoding MySQL Connection Failures in Local WordPress Environments

The error mysqli_real_connect(): (HY000/2002): No such file or directory is a classic symptom of a mismatch between how your application expects to connect to the database and how the MySQL server is actually listening. In local development setups, specifically those using MAMP on macOS, this issue often stems from the conflict between Unix socket connections and TCP/IP addresses.

When you run PHPUnit or WP-CLI against a WordPress site hosted by MAMP, the default configuration in wp-config.php typically specifies 'localhost' as the host. In many database drivers, including the one used by older PHP versions and certain configurations of MySQL/MariaDB, passing 'localhost' triggers an attempt to connect via a Unix socket file rather than a network TCP connection. This behavior differs from passing 127.0.0.1, which explicitly forces a TCP/IP connection.

If your MAMP instance is configured to listen on port 3306 but the MySQL socket path (often /tmp/mysql.sock or similar, depending on the installation) does not match what the application is looking for, or if the socket file has incorrect permissions, the mysqli_real_connect() function fails immediately with a "No such file or directory" error. This explains why switching to the PHP version supplied by MAMP might resolve WP-CLI but leave PHPUnit failing: different versions of PHP or different build configurations (like Homebrew vs. MAMP) can handle the interpretation of 'localhost' differently.

The Socket vs. TCP Dilemma

The core technical distinction lies in how the MySQL client resolves the hostname provided. When mysqli_connect is called with 'localhost', the standard behavior on Unix-like systems is to search for a socket file in the default directory (often /tmp/mysql.sock) before attempting a TCP connection. If that specific socket file does not exist at that path, or if the process running PHP lacks read permissions for it, the connection fails.

Conversely, using 127.0.0.1 bypasses the socket lookup entirely and forces the client to open a network port connection. This is why many developers find that changing the host in wp-config.php from 'localhost' to 127.0.0.1 resolves these specific errors, provided the MAMP MySQL server is actually listening on TCP/IP (port 3306) and not strictly bound to the socket interface.

Configuring WP-CLI and PHPUnit Correctly

You mentioned using phar files for both WP-CLI and PHPUnit, aliased in your ~/.bash_profile. While this is a valid approach to avoid version conflicts with system PHP, it introduces complexity when debugging connection issues because you must ensure the phar bundles are using the correct database credentials.

If you have already tried editing wp-config.php with variations like ":/path/to/mamp/mysql.socket" or "localhost:/path/to/mamp/mysql.socket", note that these formats are not standard for the MySQL client library. The mysqli extension does not accept socket paths directly as part of the host string in those formats; it expects either a hostname (which triggers socket lookup on Unix) or an IP address.

To persistently fix this without relying on runtime flags:

  1. Explicitly set the host to an IP address:
    Edit your wp-config.php file and ensure the $db_host variable is set to '127.0.0.1'. This forces the TCP connection path which is generally more reliable for local testing unless you have a specific reason to use sockets.

    define( 'DB_HOST', '127.0.0.1' );
    
  2. Verify MAMP Settings:
    Ensure that within your MAMP preferences, the MySQL server is set to allow connections on port 3306. Sometimes local hosts are configured to listen only on the socket by default for security or performance reasons in specific configurations. If you switch to TCP, verify that the firewall isn't blocking localhost traffic (rare, but possible).

Why PHPUnit Might Differ from WP-CLI

The observation that changing the PHP version fixed WP-CLI but not PHPUnit suggests a divergence in how these tools initialize their database connections. WP-CLI often has built-in logic to detect the environment and fall back to TCP if a socket connection fails, whereas PHPUnit might be strictly adhering to the configuration passed to the WP class or the underlying mysqli object without fallbacks.

Additionally, phar files are self-contained. If you installed the phar versions using an older PHP version, that executable might be hardcoded to use legacy socket paths that no longer exist in your current MAMP installation. Upgrading the phar file to match the newer PHP version (or vice versa) ensures consistent behavior regarding socket resolution.

Debugging with Error Logging

If modifying wp-config.php does not resolve the issue, inspect the raw error log generated by MAMP's MySQL server. Look for messages indicating that no connections are being accepted on port 3306 or that the socket file permissions are restricted. You can check the status of the socket file using standard Unix commands like ls -l /tmp/mysql.sock (adjusting the path based on your specific MAMP installation).

Ensuring that the user running the PHP process (often _mysql or a specific user defined in MAMP) has read permissions on the socket file is crucial when relying on socket connections. However, given the prevalence of TCP-based local development tools, sticking to 127.0.0.1 remains the most robust configuration strategy for avoiding these platform-specific socket resolution errors.

For further guidance on configuring database connections in modern PHP environments, including best practices for secure local development setups, resources like https://laravelcompany.com offer detailed documentation that can help refine your approach to connection pooling and credential management.

Our network