What the message looks like
ERROR 2002 (HY000): Can't connect to local MySQL server through socket '/var/run/mysqld/mysqld.sock' (2)Common causes
- The database service is not running: stopped, crashed, or killed by the OOM killer.
- The server did not start because the disk is full or the data directory is damaged or has wrong permissions.
- Client and server use different socket paths, e.g.
/run/mysqld/mysqld.sockand/var/lib/mysql/mysql.sock. - The application connects to
localhost, which means the socket, while the server only listens on TCP. - A second instance or a container uses another socket.
Check
- Is the service running?
systemctl status mariadb - Why did it stop? Read the latest log lines
- Does the socket exist?
ls -l /run/mysqld/ - Is there free space for the data directory?
df -h /var/lib/mysql
Fix
- Start the service and read why it stopped:
systemctl start mariadb. On MySQL the unit is calledmysql. - Free disk space or repair permissions on
/var/lib/mysqlif that was the reason. - If the OOM killer stopped it, reduce memory use (
innodb_buffer_pool_size) or add RAM. - Use the same socket path in the
[client]and[mysqld]sections of the configuration. - In the application, use
127.0.0.1and port 3306 instead oflocalhostto connect over TCP.
Typical scenario
You moved a PHP application into a Docker container while the database stays on the host. The config still says DB_HOST=localhost, and the page shows error 2002 with the path /var/run/mysqld/mysqld.sock. That socket file does not exist inside the container because it lives in the host's file system. First check whether the client runs on the same system as the server at all, and switch the host to an IP address.
FAQ
What is the difference between localhost and 127.0.0.1 here?
With localhost the MySQL client uses the Unix socket file. With 127.0.0.1 it uses TCP. If the socket is missing but TCP works, that explains this error.
Which error do I get when the password is wrong?
That is ERROR 1045. Error 2002 comes before: the client does not even reach the server.
Why does the error appear right after a reboot although everything worked before?
The socket file normally lives in /run, a volatile directory, and is only created when the server starts. If the service does not come up after boot, for example because a disk is not mounted yet or is full, there is no socket and you get error 2002.
Is my data gone when error 2002 appears?
No. The error only says that no server answers at the expected path. Your data sits in the data directory, usually /var/lib/mysql, untouched. Check free space and permissions there before you delete or re-initialize anything.
How do I find out which socket path my client expects?
The command-line client shows it with mysql --help | grep -i socket. In PHP, mysqli.default_socket and pdo_mysql.default_socket decide. The server uses the socket value from the [mysqld] section; both must match. If they differ, the client looks in the wrong place even though the server is running fine.