The client cannot reach the MySQL or MariaDB server through its Unix socket file
ERROR 2002 (HY000): Can't connect to local MySQL server through socket '/var/run/mysqld/mysqld.sock' (2)Short answer
Error 2002 means the client tried the Unix socket file named in the message and found nothing it could talk to. Either the server is not running, the server's socket file is at a different path than the client expects, or the client used localhost where it should use TCP. Ask the server for its real socket path, then make both sides use it.
Fix it fast
1Find out which cause you have
Find out whether a server is running at all and which Unix socket it listens on. If no mysqld or mariadbd process exists, the fix is to start it. If one exists and listens on a path that differs from the one in your error message, the paths do not match. The number at the end of the message is the operating system error: 2 means the file is not there, 111 means a file exists but nothing answers.
ps -eo pid,user,args | grep -E '[m]ysqld|[m]ariadbd' sudo ss -xlp | grep -E 'mysql|mariadb' # the (2) or (111) at the end of the error is errno; confirm what it means: python3 -c "import os; print(os.strerror(2), '|', os.strerror(111))"2Match what you see, then jump to its fix
- 1
The first-step check finds no mysqld or mariadbd process, and the socket path in the error does not exist on disk.The server is not runningFix - 2
The server is running and ss shows its socket, but at a different path than the one in the error message (for example /run/mysqld/mysqld.sock against /tmp/mysql.sock).The server and the client use different socket pathsFix - 3
The app runs in a container, another VM or a different user's chroot, or the database is on another host, and the error appears only when the host is written as localhost.localhost made the client use a socket that does not exist on this machineFix - 4
The server process runs, but the socket path from its config is missing, or exists and returns 'Permission denied' (error 13) for a non-root user.The socket file was deleted, or the client cannot open its directoryFix
- 1
What does the error look like?
ERROR 2002 (HY000): Can't connect to local MySQL server through socket '/var/run/mysqld/mysqld.sock' (2)ERROR 2002 (HY000): Can't connect to local server through socket '/run/mysqld/mysqld.sock' (2) (MariaDB client wording)SQLSTATE[HY000] [2002] No such file or directoryCan't connect to local MySQL server through socket '/tmp/mysql.sock' (111)
Cause 1 of 4
The server is not running
1Check
Ask systemd for the state of the service. The unit name depends on the package: mysql on Debian and Ubuntu MySQL packages, mysqld on RPM-based MySQL packages, mariadb for MariaDB. The server's own error log or the journal says why it stopped.
systemctl status mysql # or: mysqld, mariadb
journalctl -u mysql -n 50 --no-pager2Fix
Start the service, and enable it if it should survive a reboot. If it starts and dies again, the last lines of the log name the reason (a full disk, a bad option in the config file, a damaged data directory) and that reason is the real problem.
sudo systemctl start mysql # or: mysqld, mariadb
sudo systemctl enable mysql3Verify
The client connects, and the socket file now exists.
mysqladmin version # MariaDB 10.5+: mariadb-admin status
sudo ss -xl | grep -E 'mysql|mariadb'Confirmed by dev.mysql.com
Cause 2 of 4
The server and the client use different socket paths
1Check
The path in the error is the one the client tried. The path the server listens on comes from its socket option. Compare them, and see which option files the client reads.
sudo ss -xl | grep -E 'mysql|mariadb'
mysql --print-defaults # MariaDB: mariadb --print-defaults
mysql --socket=/run/mysqld/mysqld.sock -u root -p -e "SHOW VARIABLES LIKE 'socket'"2Fix
Give both sides the same path. Putting socket in an option group that server and client both read keeps them in step; MariaDB documents [client-server] for that, and MySQL clients read [client]. For a single command, pass --socket. For PHP, set the path in php.ini or in the DSN, but do not combine unix_socket with host or port in one DSN.
# /etc/mysql/conf.d/socket.cnf (MariaDB: put the same line under [client-server])
[mysqld]
socket = /run/mysqld/mysqld.sock
[client]
socket = /run/mysqld/mysqld.sock
# one command
mysql --socket=/run/mysqld/mysqld.sock -u root -p
# php.ini (pdo_mysql only reads it when built against mysqlnd, which is the usual build)
pdo_mysql.default_socket = /run/mysqld/mysqld.sock
mysqli.default_socket = /run/mysqld/mysqld.sock
// or in PHP: socket only, no host or port
$pdo = new PDO('mysql:unix_socket=/run/mysqld/mysqld.sock;dbname=app', $user, $pass);3Verify
Connect without any flag, then restart PHP so it rereads php.ini.
mysql -u root -p -e "SELECT 1"
sudo systemctl restart php8.3-fpm # your FPM service nameConfirmed by mariadb.com
Cause 3 of 4
localhost made the client use a socket that does not exist on this machine
1Check
The MySQL manual documents that localhost means the Unix socket file, while 127.0.0.1 means TCP/IP over loopback. The PHP manual says the same for PDO. If the database is not in the same machine and filesystem as the client, a socket path can never work. Try TCP to the real address.
mysql -h 127.0.0.1 -P 3306 --protocol=TCP -u root -p -e "SELECT 1"
# database on another host or in another container:
mysql -h db.internal -P 3306 -u app -p -e "SELECT 1"2Fix
Write the real host (or 127.0.0.1 for the same machine with a TCP listener) in the connection settings, and a port when it is not 3306. If TCP to loopback is refused, the server may be started with skip_networking, or bound to a different address with bind_address; both are documented in the same MySQL page.
// PDO
$pdo = new PDO('mysql:host=127.0.0.1;port=3306;dbname=app;charset=utf8mb4', $user, $pass);
# .env style
DB_HOST=127.0.0.1
DB_PORT=33063Verify
The application connects, and the process list shows a TCP connection from your client.
mysql -h 127.0.0.1 -u root -p -e "SELECT CONNECTION_ID(), @@port, @@skip_networking"Confirmed by dev.mysql.com
Cause 4 of 4
The socket file was deleted, or the client cannot open its directory
1Check
The MySQL manual lists a cleanup job that wipes the socket from /tmp, and file permissions on the socket or its directory, as causes. Look at the file and every directory above it.
ls -ld /run/mysqld /run/mysqld/mysqld.sock
namei -l /run/mysqld/mysqld.sock2Fix
Move the socket out of any directory that a cleanup job empties, then restart the server so it creates the file again. If permissions are the problem, give the client's user access to the socket's directory, or start the server with a socket path both sides can open.
# my.cnf: use a path that is not under /tmp
[mysqld]
socket = /run/mysqld/mysqld.sock
sudo systemctl restart mysql3Verify
The socket exists after the restart and the unprivileged user connects.
ls -l /run/mysqld/mysqld.sock
mysql -u app -p -e "SELECT 1"Confirmed by dev.mysql.com
How do I stop it coming back?
- Set socket once, in the option group both server and client read, rather than relying on compiled-in defaults that differ between packages.
- Use a TCP host and port in application config for anything that is not on the same machine, and keep localhost for the local socket on purpose.
- Keep the socket out of /tmp, where cleanup jobs can remove it.
- After changing the socket path, restart PHP-FPM as well as the database, since PHP reads php.ini only at start.
Sources
How was this page made?
I drafted this page with AI assistance from the official documents listed under Sources. Every cause above names the document that confirms it. I have not reproduced this fix on a machine of my own yet, so read it as documented guidance, not a test report. Found a mistake? Tell me.
Which stack is behind this page?
Projects of mine built on the same technologies:
- TaxiDexMy own multi-tenant taxi dispatch SaaS: API, dispatcher portal, driver and passenger apps, and the servers underneath.
- QistLockA NestJS and React SaaS driving an Android Device Owner agent that locks financed phones when payments lapse.
- ShopGoAn e-commerce aggregator with a Python scraping engine behind its catalog, past 10K Google Play downloads.
Related fixes
Databases
PHP throws "could not find driver" when it opens a PDO connection
Fatal error: Uncaught PDOException: could not find driver in /var/www/app/db.php:12
PDO is only a layer; each database needs its own driver extension, such as pdo_mysql or pdo_pgsql, and the DSN prefix must name a driver that is loaded.
4 causes, each with a fixDatabases
Installing the Airflow MySQL provider fails on pkg-config or mysqlclient
Building the mysqlclient wheel fails during the install
The Airflow MySQL provider depends on mysqlclient, which pip compiles against the MySQL C client library.
2 causes, each with a fixDatabases
Compiling a C or C++ program that includes mysql.h fails
undefined reference to `mysql_init'
The compiler only finds mysql.h when the MySQL client development files are installed and their folder is on the include path.
3 causes, each with a fixDatabases
An EC2 instance cannot reach its RDS database
Could not open connection to the host, on port <port>: Connect failed
RDS denies all access until a security group allows it.
3 causes, each with a fixDatabases
PHP cannot connect to SQL Server through FreeTDS
Connection Refused
FreeTDS prints this when it cannot open a session with the server name you gave it.
3 causes, each with a fixDatabases
Laravel bulk insert fails with 'too many placeholders'
SQLSTATE[HY000]: General error: 1390 Prepared statement contains too many placeholders
Laravel sends one placeholder per value, so one insert of many rows times many columns, or a whereIn with a huge list, creates a statement MySQL refuses.
3 causes, each with a fix