MySQL Error 2002 — Is the Server Down or the Socket Path Wrong?
Diagnosing Error 2002 via OS errno (2, 111, 13, 28), UNIX socket path mismatches, process status, file permissions, and Docker loopback vs socket semantics.
Operational Verification & Reliability Metadata
The error string is a symptom, not the root cause. Do not restart the server blindly. Run the diagnostic queries below to pinpoint the actual failure mode.
▸Symptom
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 MySQL server through socket '/tmp/mysql.sock' (111)
ERROR 2002 (HY000): Can't connect to local MySQL server through socket '/var/run/mysqld/mysqld.sock' (13)While PostgreSQL signals connection failures via connection refused (H-07), MySQL surfaces local socket communication failures as Error 2002. The decisive diagnostic clue is encapsulated in the operating system errno inside the parentheses:
- •(2) ENOENT — No such file or directory: The socket file does not exist at the requested filesystem path. Either
mysqldis down or the client is probing the wrong directory. - •(111) ECONNREFUSED — Connection refused: The socket file exists on disk, but no active daemon is bound to it. The typical scenario is a crashed
mysqldprocess leaving behind a stale.sockfile. - •(13) EACCES — Permission denied: The socket file exists, but the connecting OS user lacks read/write permissions on the file or traverse permissions on the parent directory. Alternatively, AppArmor/SELinux is restricting access.
▸Crucial Architectural Nuance: `localhost` ≠ `127.0.0.1`
Across MySQL client connectors (PHP PDO, Node.js mysql2, Python mysqlclient, Go-SQL-Driver):
- •Specifying `localhost` bypasses TCP networking entirely and forces UNIX domain socket communication.
- •Specifying `127.0.0.1` routes traffic through the TCP loopback interface on port 3306.
This produces a ubiquitous dilemma:
- •
mysql -h 127.0.0.1 -P 3306 -u root -p→ Succeeds immediately! - •
mysql -h localhost -u root -p→ Fails with ERROR 2002!
If TCP loopback succeeds, MySQL is fully operational; the issue is strictly a socket path discrepancy.
▸Diagnostic Step-by-Step Flow
1. Validate mysqld Process State
systemctl status mysql --no-pager
# or
ps aux | grep mysqld2. Locate Active Sockets and Listeners
ss -lnp | grep -E '3306|.sock'
ls -la /var/run/mysqld/If the socket file exists but ss shows no active listening process, you are experiencing errno (111). The stale socket file must be removed before restarting.
3. Cross-Check Client vs Server Defaults
Inspect the compiled defaults on disk:
my_print_defaults mysqld | grep -E 'socket|port|bind'
my_print_defaults client | grep 'socket'If the daemon binds to /var/run/mysqld/mysqld.sock while the client searches in /tmp/mysql.sock, communication is impossible.
4. The Storage Exhaustion Trap (Errcode: 28)
If the filesystem hosting runtime directories fills up completely, mysqld cannot create its socket or PID file:
[ERROR] Can't create/write to file '/var/run/mysqld/mysqld.sock' (Errcode: 28 - No space left on device)Check df -h on /var and /tmp.
5. Container & Docker Volume Isolation
In containerized environments, the MySQL socket resides within the container's isolated mount namespace. To access it from the host, the directory must be mounted as a shared volume. Additionally, inside a container, localhost references the container itself, not the host machine.
▸Step-by-Step Resolution
1. Inspect Server Logs Before Blind Restarts
Do not execute blind service restarts; diagnose failure reasons from the error log:
tail -n 100 /var/log/mysql/error.logCommon causes include Linux OOM-Killer interventions and disk capacity exhaustion (Errcode: 28).
2. Standardize Client Connections on TCP Loopback
Change application connection parameters from DB_HOST=localhost to DB_HOST=127.0.0.1. This completely eliminates socket path mismatches.
3. Unify Socket Paths in Configuration
[mysqld]
socket=/var/run/mysqld/mysqld.sock
[client]
socket=/var/run/mysqld/mysqld.sockEnsure correct directory permissions:
mkdir -p /var/run/mysqld
chown -R mysql:mysql /var/run/mysqld
chmod 755 /var/run/mysqld4. Verify TCP Networking Availability
SHOW VARIABLES LIKE 'skip_networking';
SHOW VARIABLES LIKE 'bind_address';If skip_networking = ON, MySQL rejects all TCP connections and operates exclusively via UNIX domain sockets.
▸Related Error Guides & Hub Links
- •PostgreSQL Connection Refused (H-07) — PostgreSQL connection refusal counterpart
- •MySQL Too Many Connections (H-32) — Connection pool saturation
- •MySQL No Space Left on Device (H-17) — Disk exhaustion and Errcode 28
- •MySQL Hub — MySQL operations and server architecture
Other Database Error Triage Playbooks
Other battle-tested diagnostic guides for high-severity database errors.
MySQL ERROR 1045 Access denied: root Password Reset Guide
Four causes of MySQL 1045, meaning of using password: YES/NO, and safe credential recovery via --init-file.
MySQL Deadlock ERROR 1213: Graph Analysis and Permanent Prevention
Root causes of MySQL 1213 deadlock, parsing LATEST DETECTED DEADLOCK output, gap lock concurrency issues, and resilient application retry design.
MySQL Lock wait timeout exceeded: Finding Blocking Sessions
Finding the blocking transaction using performance_schema, safe KILL decision matrices, and permanent locking reduction.