Maaz Zindani

Loading the index…

↑↓ move↵ openesc close4072 pages
Databases and Redis

The client cannot reach the MySQL or MariaDB server through its Unix socket file

ErrorERROR 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.

  • Applies to MySQL 8.4 LTS, MariaDB 11.4, PHP 8.3 and 8.4 (PDO and mysqli), Ubuntu 24.04
  • Updated
  • By Maaz Zindani, Senior Software Engineer

Fix it fast

  1. 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))"
  2. 2Match what you see, then jump to its fix

    1. 1The 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. 2The 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. 3The 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. 4The 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

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 directory
  • Can'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-pager

2Fix

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 mysql

3Verify

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

Did this fix it?

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 name

Confirmed by mariadb.com

Did this fix it?

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=3306

3Verify

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

Did this fix it?

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.sock

2Fix

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 mysql

3Verify

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

Did this fix it?

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:

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 fix

Databases

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

Next step

Want this handled for good?

I look after servers, apps and releases end to end. Tell me what keeps breaking.