Fix "mysqli_real_connect(): (HY000/2002): No such file or directory" in WordPress

TL;DR — Quick Fix

Open wp-config.php and swap localhost for 127.0.0.1 in the DB_HOST line:

// Before
define( 'DB_HOST', 'localhost' );

// After
define( 'DB_HOST', '127.0.0.1' );

That one change makes PHP connect via TCP instead of hunting for a Unix socket file. Reload the site. If it works — you're done. If not, keep reading.

Why This Happens

PHP's MySQLi has a compiled-in default socket path — often /tmp/mysql.sock. Your MySQL or MariaDB installation almost certainly puts the socket somewhere else, like /var/run/mysqld/mysqld.sock or /var/lib/mysql/mysql.sock. Those paths don't match. PHP can't find the file. WordPress breaks.

The most common mismatches:

• PHP compiled with /tmp/mysql.sock, but MySQL actually uses /var/run/mysqld/mysqld.sock
• MariaDB socket at /var/lib/mysql/mysql.sock while PHP looks elsewhere
• MySQL was reinstalled or upgraded and the socket moved to a new location
• MySQL runs inside Docker or a VM — the socket path doesn't exist on the host

This error is more specific than WordPress's generic white-screen "Error establishing a database connection." It bleeds into PHP output directly and names the exact failure point:

Warning: mysqli_real_connect(): (HY000/2002): No such file or directory in /var/www/html/wp-includes/class-wpdb.php

That's actually useful. It tells you it's a socket problem — not a wrong password or a missing database.

Fix 1 — Switch to TCP (Fastest)

Edit /var/www/html/wp-config.php (adjust the path if your WordPress lives somewhere else):

define( 'DB_HOST', '127.0.0.1' );

TCP on port 3306. No socket file involved. One condition: MySQL must be listening on the loopback interface. Confirm it is:

ss -tlnp | grep 3306

You want output like this:

LISTEN  0  151  127.0.0.1:3306  0.0.0.0:*  users:("mysqld",...)

Nothing there? MySQL is socket-only. Jump to Fix 2 or Fix 3.

Fix 2 — Find the Real Socket and Point PHP to It

Track down where MySQL actually put its socket:

# Ask MySQL directly
mysql -e "SHOW VARIABLES LIKE 'socket';"

# Search the config files
grep -r "socket" /etc/mysql/ /etc/my.cnf /etc/my.cnf.d/ 2>/dev/null

# Or just find it on disk
find /var/run /tmp /var/lib/mysql -name "*.sock" 2>/dev/null

Once you have the real path, pass it directly into wp-config.php:

// host:socket format — WordPress passes this straight to MySQLi
define( 'DB_HOST', 'localhost:/var/run/mysqld/mysqld.sock' );

MySQLi accepts the host:socket_path format natively. No hacks needed.

Fix 3 — Set the Default Socket in php.ini

Want a fix that applies to every PHP app on the server, not just WordPress? Set it in php.ini.

# Find the active php.ini
php --ini | grep "Loaded Configuration"

# Edit it (adjust version number to match yours)
sudo nano /etc/php/8.1/cli/php.ini

Find mysqli.default_socket and point it at your actual socket path:

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

Using PDO anywhere? Update that one too:

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

Restart PHP to pick up the change:

# PHP-FPM
sudo systemctl restart php8.1-fpm

# Apache mod_php
sudo systemctl restart apache2

Fix 4 — MySQL Isn't Running

Before chasing socket paths, rule out the obvious: MySQL crashed.

sudo systemctl status mysql
# or
sudo systemctl status mysqld

# Stopped? Start it:
sudo systemctl start mysql

# See what killed it:
sudo journalctl -u mysql -n 50 --no-pager

If MySQL keeps dying on startup, check /var/log/mysql/error.log. The real cause is almost always in there — disk full, InnoDB corruption, memory limit hit.

Fix 5 — Docker or Custom Server Setup

Running WordPress in Docker? localhost inside a container refers to the container itself — not the host machine or a sibling container. Use the actual service name or IP instead:

# Service name defined in docker-compose.yml
define( 'DB_HOST', 'db' );

# MySQL on the host — Mac/Windows Docker Desktop
define( 'DB_HOST', 'host.docker.internal' );

# MySQL on the host — Linux Docker default bridge
define( 'DB_HOST', '172.17.0.1' );

Verify the Fix

Before reloading the site, test the connection from the command line. Grab DB_USER, DB_PASSWORD, and DB_NAME from wp-config.php, then run:

# Via TCP
mysql -h 127.0.0.1 -u your_wp_user -p your_wp_database

# Via socket
mysql -S /var/run/mysqld/mysqld.sock -u your_wp_user -p

Connected without errors? WordPress will be fine. Load the site, then tail the error log to confirm it's clean:

sudo tail -f /var/log/nginx/error.log
# or
sudo tail -f /var/log/apache2/error.log

Which Fix to Use

• Shared hosting / managed server — Fix 1 (TCP). Works almost every time. Only needs access to wp-config.php, no server admin required.
• VPS with full control — Fix 1 first. Add Fix 3 if you want the socket path set globally for all apps on the machine.
• Docker setup — Fix 5. Don't bother with socket sharing between containers — TCP is simpler and more portable.
• MySQL not running — Fix 4 first. Nothing else matters until the service is actually up.