MySQL ERROR 2002 (HY000): Can't Connect to Local MySQL Server Through Socket

Short answer

ERROR 2002 is a connection problem, not a password problem. It has three usual causes:

1. The MySQL server is not running, so there is no socket file to connect to.
2. The client looks for the socket at the wrong path (for example /tmp/mysql.sock while the server writes /var/run/mysqld/mysqld.sock).
3. localhost means "use the socket". MySQL clients connect to localhost through the Unix socket file, while 127.0.0.1 uses TCP. If the socket is broken, localhost fails and 127.0.0.1 may work.

Quickest checks:

# 1. Is the server running?
sudo systemctl status mysql      # Debian/Ubuntu (RHEL/Fedora: mysqld)
brew services list               # macOS Homebrew

# 2. Does TCP work? If yes, the server is up and only the socket path is wrong.
mysql -u root -p -h 127.0.0.1 -P 3306

# 3. Where does the server put its socket? (run over TCP)
mysql -u root -p -h 127.0.0.1 -e "SELECT @@socket;"

The Error Message

The exact wording depends on the client and platform. All of these are the same error:

The number in parentheses at the end is the operating system error code. (2) means "no such file or directory": the socket file does not exist at that path. (111) means the connection was refused (a stale socket file with no server behind it), and (13) means permission denied on the socket or its directory.

The path in the message tells you which socket the client was looking for. It is not necessarily where the server put it. Typical defaults:

• /tmp/mysql.sock: MySQL's built-in default, used by macOS Homebrew and the official tarball builds.
• /var/run/mysqld/mysqld.sock: Debian and Ubuntu packages (/var/run is a link to /run).
• /var/lib/mysql/mysql.sock: RPM packages on RHEL, CentOS, Rocky, AlmaLinux, Oracle Linux and Fedora.

What Causes MySQL 2002?

MySQL Error 2002 means the MySQL client can't find or connect to the MySQL server's socket file. The MySQL manual describes it as: there is no MySQL server running on the system, or you are using an incorrect Unix socket file name or TCP/IP port number when trying to connect to the server.

Common Causes

How to Fix It

Step 1: Check if MySQL is running

First verify that the MySQL server process is actually running.

# Linux (Debian/Ubuntu service name is mysql, RHEL/Fedora is mysqld):
sudo systemctl status mysql

# macOS:
brew services list | grep mysql

# Or check the process:
ps aux | grep mysqld

# Ask the server directly (uses the default socket):
mysqladmin version

Step 2: Start MySQL if stopped

Start the MySQL service and check the logs if it fails to start.

# Linux:
sudo systemctl start mysql      # Debian/Ubuntu
sudo systemctl start mysqld     # RHEL/CentOS/Fedora
sudo journalctl -u mysql -n 50  # why it failed (use mysqld on RHEL)

# macOS:
brew services start mysql

# Docker:
docker start mysql-container

Step 3: Find the actual socket location

Find where MySQL actually creates the socket file, then compare it with the path in the error message.

# Ask the running server (over TCP, so the socket doesn't matter):
mysql -u root -p -h 127.0.0.1 -e "SELECT @@socket;"

# What the client will use by default (look for the "socket" line):
mysql --help | grep socket

# Check the config files:
grep -R "socket" /etc/my.cnf /etc/mysql/ 2>/dev/null

# Find socket files on disk:
sudo find / -name "*.sock" -path "*mysql*" 2>/dev/null

# Common locations:
# /var/run/mysqld/mysqld.sock   (Debian/Ubuntu)
# /tmp/mysql.sock               (macOS Homebrew, tarball builds)
# /var/lib/mysql/mysql.sock     (RHEL/CentOS/Fedora RPMs)

Step 4: Connect using the correct socket

Either specify the correct socket path or bypass sockets entirely with a TCP connection.

# Specify socket path directly:
mysql -u root -p --socket=/var/run/mysqld/mysqld.sock

# Or use TCP instead:
mysql -u root -p --host=127.0.0.1 --port=3306

# Or force TCP even with host localhost:
mysql -u root -p --protocol=TCP

Step 5: Make client and server agree on the socket path

To fix it permanently, put the same path in both sections of your option file (for example /etc/my.cnf), then restart MySQL:

[mysqld]
socket=/var/run/mysqld/mysqld.sock

[client]
socket=/var/run/mysqld/mysqld.sock

If [mysqld] says one path and [client] (or the client's built-in default) says another, the server starts fine and every localhost connection fails with ERROR 2002. You can test a path without editing anything: mysqladmin --socket=/path/to/socket version. The MYSQL_UNIX_PORT environment variable also sets the client's socket path.

Fix by Environment

macOS (Homebrew): '/tmp/mysql.sock'

Error: ERROR 2002 (HY000): Can't connect to local MySQL server through socket '/tmp/mysql.sock' (2). Homebrew MySQL uses the default socket /tmp/mysql.sock. This error almost always means the server is not running.

# Is it running?
brew services list

# Start now and at login:
brew services start mysql

# Or start it once without a background service:
mysql.server start

# Still failing? Check for a config from another install:
ls -l /etc/my.cnf /etc/mysql/my.cnf

# Read the error log (file name is <hostname>.err):
tail -n 50 "$(brew --prefix)/var/mysql/$(hostname).err"

Homebrew warns that an /etc/my.cnf or /etc/mysql/my.cnf left by another install can stop the Homebrew server from starting. If you installed a versioned formula such as mysql@8.4, use that name: brew services start mysql@8.4.

Ubuntu / Debian: '/var/run/mysqld/mysqld.sock'

Error: ERROR 2002 (HY000): Can't connect to local MySQL server through socket '/var/run/mysqld/mysqld.sock' (2). The service is named mysql on Debian-based systems.

sudo systemctl status mysql
sudo systemctl start mysql
sudo systemctl enable mysql          # start on boot
sudo journalctl -u mysql -n 50       # why it failed
sudo tail -n 50 /var/log/mysql/error.log
ls -ld /var/run/mysqld               # directory must exist, owned by mysql

/var/run/mysqld missing after reboot: /run is cleared on every boot. The packaged mysql.service recreates /run/mysqld when it starts (RuntimeDirectory=mysqld), so always start MySQL through systemctl. If you start mysqld or mysqld_safe by hand, create the directory first:

sudo mkdir -p /var/run/mysqld
sudo chown mysql:mysql /var/run/mysqld

On MariaDB the service is mariadb (sudo systemctl start mariadb); mysql usually works as an alias.

RHEL / CentOS / Rocky / Fedora: '/var/lib/mysql/mysql.sock'

Error: Can't connect to local MySQL server through socket '/var/lib/mysql/mysql.sock' (2). MySQL's RPM packages use /var/lib/mysql/mysql.sock and /etc/my.cnf, and the service is named mysqld. MySQL is not started automatically after an RPM install.

sudo systemctl status mysqld
sudo systemctl start mysqld
sudo systemctl enable mysqld
sudo journalctl -u mysqld -n 50
grep socket /etc/my.cnf

Docker

The MySQL socket is inside the container, so the host has no /var/run/mysqld/mysqld.sock or /tmp/mysql.sock to connect to. From the host, connect over TCP to a published port, never to localhost without a protocol:

# Publish the port when you create the container:
docker run -d --name mysql1 -p 3306:3306 -e MYSQL_ROOT_PASSWORD=secret mysql:8.4

# Connect from the host over TCP:
mysql -h 127.0.0.1 -P 3306 -u root -p
mysql --protocol=TCP -P 3306 -u root -p

# Or run the client inside the container, where the socket exists:
docker exec -it mysql1 mysql -uroot -p

From another container on the same Docker network, use the container name as the host (-h mysql1), not localhost. If the connection now reaches the server but is refused, that is a different error (1045 Access denied), not 2002.

XAMPP and MAMP

These bundles run their own MySQL with their own socket, so a system mysql client (or PHP from Homebrew) looking at /tmp/mysql.sock won't find it.

• MAMP (macOS): socket /Applications/MAMP/tmp/mysql/mysql.sock, TCP port 8889 by default (3306 if you chose the "80 & 3306" ports). Connect with mysql -u root -p --socket=/Applications/MAMP/tmp/mysql/mysql.sock or mysql -u root -p -h 127.0.0.1 -P 8889.
• XAMPP (macOS): start MySQL in XAMPP Control first. The socket path is set by the socket= line in /Applications/XAMPP/xamppfiles/etc/my.cnf; pass that path with --socket, or connect with -h 127.0.0.1 -P 3306.

PHP: mysqli / PDO "(HY000/2002): No such file or directory"

Errors: mysqli::real_connect(): (HY000/2002): No such file or directory, mysqli_connect(): (HY000/2002): No such file or directory, SQLSTATE[HY000] [2002] No such file or directory. With host localhost, PHP uses the Unix socket, and the socket path PHP was built with does not match your server. Two fixes:

1. Use TCP by changing the host to 127.0.0.1:

// mysqli
$db = new mysqli('127.0.0.1', 'user', 'password', 'mydb', 3306);

// PDO
$pdo = new PDO('mysql:host=127.0.0.1;port=3306;dbname=mydb', 'user', 'password');

// Laravel .env
// DB_HOST=127.0.0.1

2. Point PHP at the real socket in php.ini (find it with php --ini), then restart PHP-FPM or Apache:

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

Or set it per connection: new PDO('mysql:unix_socket=/var/run/mysqld/mysqld.sock;dbname=mydb', ...). pdo_mysql.default_socket defaults to /tmp/mysql.sock, which is why PHP on Linux often fails against a Debian/Ubuntu MySQL that uses /var/run/mysqld/mysqld.sock.

How to Prevent This Error

Set up MySQL to auto-start on boot (systemctl enable or brew services start). Keep one MySQL install per machine, or give each its own port. Keep [mysqld] and [client] socket paths identical. Monitor MySQL with a health check script. Use TCP connections (127.0.0.1:3306) in application code instead of socket connections for better portability.

Fix MySQL Errors with AI2SQL

Instead of debugging SQL syntax manually, describe what you need in plain English and let AI2SQL generate the correct query for MySQL.

Frequently Asked Questions