🚨 MySQL Error Guide: 'ERROR 2002 (HY000)' Can't Connect Through Socket

Overview

ERROR 2002 (HY000) is a client-side connection error: the client tried to reach a local MySQL server over a Unix socket file and either the file is not there or nothing is listening on it.

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

The trailing number is the errno: (2) is ENOENT — the socket file does not exist (server down or wrong path); (13) is EACCES — permission denied on the socket. The client uses the socket whenever the host is localhost (or omitted). Connecting via 127.0.0.1 instead forces TCP and bypasses the socket entirely — a useful first diagnostic.

It appears at connect time from the mysql CLI, local cron jobs, backup scripts, or any app configured to talk to localhost.

Symptoms

• Can't connect ... through socket '...' (2) from the CLI or local scripts.
• The same database is reachable via -h 127.0.0.1 but not localhost.
• After an upgrade or package reinstall, the socket path the client expects differs from where the server creates it.
• (13) permission errors for non-root local users.

mysql -u root -p

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

Common Root Causes

1. The MySQL server is not running

If mysqld is stopped or crashed, no socket file exists.

systemctl status mysql --no-pager | head -5

* mysql.service - MySQL Community Server
   Loaded: loaded (/lib/systemd/system/mysql.service; enabled)
   Active: failed (Result: exit-code) since Tue 2026-06-23 09:12:04 UTC

Active: failed (or inactive) means there is nothing to connect to. Starting the service usually resolves the 2002.

2. Client and server disagree on the socket path

The client looks for the socket at a path the server is not using (common after upgrades or distro changes: /var/run/mysqld/mysqld.sock vs /tmp/mysql.sock vs /run/mysqld/mysqld.sock).

mysql --help 2>/dev/null | grep -A1 "Default options" >/dev/null
mysql -u root -p -e "SHOW VARIABLES LIKE 'socket';" -h 127.0.0.1

+---------------+-----------------------------+
| Variable_name | Value                       |
+---------------+-----------------------------+
| socket        | /run/mysqld/mysqld.sock     |
+---------------+-----------------------------+

If the server says /run/mysqld/mysqld.sock but the client error references /var/run/mysqld/mysqld.sock, the paths differ.

3. The socket file is missing despite the server running

The runtime directory (/var/run/mysqld) was wiped (e.g. on reboot for a tmpfs) and mysqld could not recreate it, so it failed to create the socket.

ls -ld /var/run/mysqld
ls -l /var/run/mysqld/mysqld.sock

ls: cannot access '/var/run/mysqld': No such file or directory

Without the directory, mysqld cannot bind its socket and exits early.

4. Permission denied on the socket (errno 13)

The socket exists but the connecting OS user lacks permission to the file or its directory.

mysql -u app -p

ERROR 2002 (HY000): Can't connect to local MySQL server through socket '/var/run/mysqld/mysqld.sock' (13)

ls -l /var/run/mysqld/mysqld.sock

srwxrwx--- 1 mysql mysql 0 Jun 23 09:00 /var/run/mysqld/mysqld.sock

srwxrwx--- owned by mysql:mysql excludes other users — errno 13.

5. mysqld crashed on startup (config or data error)

The service tries to start but mysqld exits before creating the socket, often due to a bad config or corrupt InnoDB log.

journalctl -u mysql --no-pager | tail -15

[ERROR] [MY-010187] [Server] Could not open file '/etc/mysql/conf.d/zz.cnf' for error logging: Permission denied
[ERROR] [MY-010119] [Server] Aborting
mysqld: ready for connections ... (never reached)

The error log explains why it never came up.

6. Disk full prevents socket/temp file creation

A full filesystem stops mysqld from writing its socket or temp files.

df -h /var /tmp

Filesystem      Size  Used Avail Use% Mounted on
/dev/sda1        20G   20G     0 100% /

100% use on the partition holding the socket/datadir blocks startup.

Diagnostic Workflow

Step 1: Confirm whether the server is even running

systemctl is-active mysql && systemctl status mysql --no-pager | head -5
ps aux | grep -c '[m]ysqld'

If it is not active, that is the whole problem — go to the error log (Step 4).

Step 2: Prove it is a socket-only issue by forcing TCP

mysql -u root -p -h 127.0.0.1 -e "SELECT 1;"

If TCP works but localhost fails, the server is up and the issue is purely the socket path/permissions. If TCP also fails, the server is down or not listening.

Step 3: Find the server’s real socket path

mysql -u root -p -h 127.0.0.1 -e "SHOW VARIABLES LIKE 'socket';"
grep -R "^socket" /etc/mysql/ 2>/dev/null

Compare this to the path quoted in the 2002 error.

Step 4: Inspect the error log if the server is down

journalctl -u mysql --no-pager | tail -20
# or the configured log file:
grep -i error /var/log/mysql/error.log | tail -20

This reveals config errors, corrupt logs, or disk-full causes.

Step 5: Fix the path/permissions/dir and reconnect

# Recreate the runtime dir if missing
sudo install -d -o mysql -g mysql -m 0755 /var/run/mysqld
sudo systemctl restart mysql

# Point the client at the right socket (or fix client config)
mysql -u root -p --socket=/run/mysqld/mysqld.sock

To make the client default correct, set socket= under [client] in /etc/mysql/my.cnf to match the server.

Example Root Cause Analysis

After an OS package update, a backup cron job starts failing every night:

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

The DBA forces TCP to check the server is alive:

mysql -u root -p -h 127.0.0.1 -e "SHOW VARIABLES LIKE 'socket';"

+---------------+-------------------------+
| Variable_name | Value                   |
+---------------+-------------------------+
| socket        | /run/mysqld/mysqld.sock |
+---------------+-------------------------+

The server is fine and listening on /run/mysqld/mysqld.sock. But the client error references /tmp/mysql.sock — the update reset a packaged /etc/my.cnf that hard-codes the old socket path under [client]. The cron job’s mysql client reads it and looks in the wrong place.

Fix: align the client config with the server’s actual socket:

# /etc/mysql/my.cnf
[client]
socket = /run/mysqld/mysqld.sock

The next cron run connects normally. (Using -h 127.0.0.1 in the job would also have sidestepped the socket entirely.)

Prevention Best Practices

• Keep the [client] and [mysqld] socket= settings identical and managed by config management so package updates cannot drift them apart.
• For local apps and scripts, prefer connecting to 127.0.0.1 (TCP) when the socket path is volatile across environments; reserve socket connections for fixed, owned hosts.
• Ensure the runtime directory (/var/run/mysqld) is recreated on boot with correct ownership — use the packaged tmpfiles.d entry rather than relying on a persisted directory.
• Monitor mysql.service state and disk usage on the datadir/socket partition so a stopped server or full disk pages you before clients see 2002.
• After any MySQL upgrade, run a connection smoke test over both socket and TCP before declaring the maintenance done.
• For quick triage of a startup failure behind a 2002, the free incident assistant can summarize the error log into a likely cause. More in MySQL guides.

Quick Command Reference

# Is the server running?
systemctl status mysql --no-pager | head -5
ps aux | grep '[m]ysqld'

# Force TCP to isolate socket-only issues
mysql -u root -p -h 127.0.0.1 -e "SELECT 1;"

# Server's real socket path vs. the error's path
mysql -u root -p -h 127.0.0.1 -e "SHOW VARIABLES LIKE 'socket';"
grep -R "^socket" /etc/mysql/

# Inspect socket file + permissions
ls -ld /var/run/mysqld
ls -l /var/run/mysqld/mysqld.sock

# Why is the server down?
journalctl -u mysql --no-pager | tail -20

# Recreate runtime dir and restart
sudo install -d -o mysql -g mysql -m 0755 /var/run/mysqld
sudo systemctl restart mysql

# Connect via an explicit socket
mysql -u root -p --socket=/run/mysqld/mysqld.sock

Conclusion

ERROR 2002 (HY000) is the client failing to reach a local server over its Unix socket. The errno tells you which way: (2) no socket file, (13) permission denied. The usual root causes:

1. The MySQL server is stopped or crashed, so no socket exists.
2. The client and server disagree on the socket path (common post-upgrade).
3. The runtime directory was wiped and mysqld could not recreate the socket.
4. Permissions on the socket file exclude the connecting OS user (errno 13).
5. mysqld crashes on startup due to a config, corrupt-log, or other error.
6. A full disk prevents the socket or temp files from being created.

Force a TCP connection with -h 127.0.0.1 first — that single test tells you whether the server is down (fix startup) or the socket path/permissions are wrong (align client and server config).