ERROR 2002 (HY000): Can't connect to local MySQL server through socket

What it means

The mysql and mariadb command-line clients treat the host name localhost specially: instead of opening a TCP connection, they connect through a Unix socket file such as /tmp/mysql.sock. Error 2002 means that file couldn’t be used. Your client never reached a server, so this has nothing to do with your user name or password yet.

The number in brackets at the end is the operating system’s reason:

Because localhost means “use the socket”, the client ignores the port you give with it. -h localhost -P 3307 doesn’t go to port 3307.

Common causes

1. The server isn’t running on this machine: it stopped, crashed, or was never started.
2. The server is in Docker, a VM or on another machine. Its socket file is there, not on your Mac, so your client finds nothing. You need TCP.
3. The client and server disagree about the socket path. Builds and packages put it in different places (/tmp/mysql.sock, /var/run/mysqld/mysqld.sock, /run/mysqld/mysqld.sock).
4. A stale socket file from a server that crashed, or a socket deleted by something that cleans /tmp.

How to fix it

Use TCP when the server isn’t local

If the server is in Docker or anywhere else, connect to an IP address and port instead of localhost:

mysql -h 127.0.0.1 -P 3306 -u <user> -p

--protocol=TCP does the same if you want to keep localhost. In application config, set the host to 127.0.0.1 rather than localhost. If TCP then fails with “Can’t connect to MySQL server on…”, see error 2003.

Check the server is running

On a Mac with Homebrew:

brew services list
brew services start mysql      # or mariadb

On Linux with systemd, systemctl status mysql (or mariadb); the error log says why it stopped. You can also look for the process with ps aux | grep -E 'mysqld|mariadbd'.

Find where the server puts its socket

If you can connect any other way (TCP, or another client), ask the server:

SELECT @@socket;

Then point the client at it with --socket=<path>, or set it once in ~/.my.cnf:

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

A stale socket

If the error ends in (111) (Linux) or (61) (macOS), the file exists but nothing listens on it: the server that made it has gone. Start the server again (and check its error log for why it stopped); a running server answers on its socket.

Reproduce it

With the clients in the MySQL 8.4.11 and MariaDB 11.4.13 Docker images, pointing at a socket path nothing listens on:

mysql -uroot -p -S /tmp/mysql.sock -e 'select 1'

ERROR 2002 (HY000): Can't connect to local MySQL server through socket '/tmp/mysql.sock' (2)

MariaDB’s client drops the word “MySQL”:

ERROR 2002 (HY000): Can't connect to local server through socket '/tmp/mysql.sock' (2)

A socket file that exists with no server behind it (created and left behind by a process that exited) gives (111), connection refused:

ERROR 2002 (HY000): Can't connect to local server through socket '/tmp/seo_stale.sock' (111)

And localhost ignores the port: this connected through the server’s socket even though nothing listens on port 3399:

mysql -hlocalhost -P3399 -uroot -p -e 'select @@port'

@@port
3306

Adding --protocol=TCP made the client honour the port, and the error became 2003:

ERROR 2003 (HY000): Can't connect to MySQL server on 'localhost:3399' (111)

Note that MariaDB 11.4’s own client also reports TCP failures as 2002, as Can't connect to server on '127.0.0.1' (115); that one is a network problem, covered under error 2003.

In Inlet

When Inlet can’t reach the server, the connection window shows the reason with a hint. For a server in Docker or on another machine, use 127.0.0.1 or its address and the published port; for one you can only reach through a bastion, Inlet’s SSH tunnel uses the system ssh, so your ~/.ssh/config and SSH agent work.