MySQL "Can't connect to local MySQL server through socket": find out why (ERROR 2002)

1. Is the server running?

sudo systemctl status mysql

The service name depends on the system: mysql on Debian and Ubuntu, mysqld on RHEL-family systems, mariadb for MariaDB. If it’s inactive, start it:

sudo systemctl start mysql

If that fails, the log says why. The general error log is usually in /var/log/mysql/error.log on Ubuntu, or /var/log/mysqld.log on RHEL:

sudo journalctl -u mysql -n 30 --no-pager
sudo tail -n 30 /var/log/mysql/error.log

The usual reasons:

• The disk is full. MySQL can’t write, so it stops or won’t start: see No space left on device.
• Not enough memory. The kernel killed it, and the log just ends: see Linux process “Killed”.
• A bad setting after you edited my.cnf: the log names the line (unknown variable).
• Port 3306 is taken, by a second MySQL or a container: see Address already in use.
• Wrong owner on the data folder after a restore: sudo chown -R mysql:mysql /var/lib/mysql.

For the general method, see Job for … failed because the control process exited.

2. The server runs, but the socket is elsewhere

Ask the system where the server’s socket is:

sudo ss -xlnp | grep -i mysql

u_str LISTEN 0 151 /var/lib/mysql/mysql.sock 28411 * 0 users:(("mysqld",pid=1021,fd=24))

The default depends on the distribution: /var/run/mysqld/mysqld.sock on Debian and Ubuntu, /var/lib/mysql/mysql.sock on RHEL. If the client looks in a different place from the server, tell it where, once:

mysql --socket=/var/lib/mysql/mysql.sock -u root -p

or permanently, in the same place for both, in /etc/my.cnf or /etc/mysql/my.cnf:

[mysqld]
socket=/var/lib/mysql/mysql.sock

[client]
socket=/var/lib/mysql/mysql.sock

Restart the server after changing it. mysql --help | grep -A1 'Default options' lists the config files it reads, and in which order.

3. localhost is not 127.0.0.1

This surprises almost everyone. On Unix, MySQL clients treat the name localhost specially and use the socket. To use TCP, give the address:

mysql -h 127.0.0.1 -P 3306 -u root -p

So if the socket path is the problem, this works right away. It’s also useful as a test: if TCP works and the socket doesn’t, the server is fine and you’re looking at a path or permission problem. If neither works, the server isn’t running, or doesn’t listen where you think. See sudo ss -tlnp | grep 3306, and the Port Lookup entry for 3306.

The same applies to applications: in PHP, Python or Node.js, host: localhost may mean the socket, and host: 127.0.0.1 means TCP.

4. Inside Docker

With MySQL in a container, its socket is inside the container. A client on the host, or in another container, has no such file. Connect over TCP instead:

docker compose exec db mysql -u root -p        # from inside the container: the socket works
mysql -h 127.0.0.1 -P 3306 -u root -p          # from the host, with the port published

Between containers, use the service name as the host (db), not localhost: see connecting from a container to localhost.

5. (111) or (13)

(111) means the file exists, but no server listens on it. It’s often left behind by a crash. Start the server, which normally replaces it. If it complains, and you’ve made sure no mysqld is running (pgrep -a mysqld), remove the stale socket and its lock file, and start again.

(13) means permissions: check every folder on the way with namei -l /var/run/mysqld/mysqld.sock. On RHEL, a socket in a non-standard folder needs the right SELinux label; on Ubuntu, AppArmor limits where mysqld may write (sudo dmesg | grep -i apparmor).