This MySQL connection error occurs when the client cannot establish a Unix socket connection to a local MySQL server. The error typically indicates that the MySQL server is not running, the socket file doesn't exist or is inaccessible, or the client is looking for the socket in the wrong location.
The ERROR 2002 (HY000) is a MySQL client error that specifically relates to Unix socket-based connections to local MySQL servers. Unlike error 2003 which applies to TCP/IP network connections, error 2002 is specific to local IPC (Inter-Process Communication) via Unix domain sockets. Key aspects of this error: 1. **Socket-Based Communication**: This error occurs when the MySQL client attempts to connect to a local MySQL server using a Unix socket file (typically /var/run/mysqld/mysqld.sock, /tmp/mysql.sock, or similar). The client cannot locate or access this socket file. 2. **Socket File Lifecycle**: The socket file is created when the MySQL server starts and deleted when it stops. If the server crashes unexpectedly or the file system is cleaned automatically (common in /tmp directories), the socket file disappears. 3. **Local Connections Only**: This error only affects local connections via localhost or socket file specification. Remote connections using TCP/IP (host:port) would result in error 2003 instead. 4. **Permission Requirements**: The Unix socket file requires proper file permissions and ownership. The MySQL server process creates the socket, and clients must have read/write permissions to connect through it. This error is extremely common in local development environments, Docker containers, fresh MySQL installations, and scenarios where the MySQL service has stopped or failed to start.
First, verify that the MySQL server process is active:
# Check MySQL service status
sudo systemctl status mysql
# or
sudo systemctl status mysqld
# or
sudo service mysql status
# Check if MySQL process exists
ps aux | grep mysqld
sudo pgrep -a mysqld
# Check for socket file existence
ls -la /var/run/mysqld/mysqld.sock
ls -la /tmp/mysql.sock
ls -la /var/lib/mysql/mysql.sock
# Start MySQL if not running
sudo systemctl start mysql
# or
sudo service mysql start
# Check MySQL error logs for startup issues
sudo tail -50 /var/log/mysql/error.log
sudo journalctl -u mysql -n 50If MySQL won't start, the error log will show the reason (permissions, disk space, configuration errors, port already in use, etc.).
Ensure the socket file exists and is accessible:
# Find where socket file actually is
sudo find / -name mysqld.sock 2>/dev/null
sudo find /var /tmp -name "mysql.sock*" 2>/dev/null
# Check socket file details
ls -la /var/run/mysqld/mysqld.sock
stat /var/run/mysqld/mysqld.sock
# Check directory permissions
ls -la /var/run/mysqld/
ls -la /var/lib/mysql/
# Expected permissions:
# Socket file: srwxrwxrwx (777) or similar
# Owner: mysql:mysql
# Directory: drwxr-x--- or drwxr-xr-x
# If permissions are wrong, fix them
sudo chmod 755 /var/run/mysqld
sudo chown mysql:mysql /var/run/mysqld/mysqld.sock
# Ensure mysql user can access directory
sudo chown mysql:mysql /var/run/mysqld
sudo chmod 755 /var/run/mysqldIf socket file doesn't exist after MySQL starts, the server failed to initialize properly.
Verify MySQL server and client are configured to use the same socket path:
# Check what socket path the running MySQL uses
sudo mysql -e "SELECT @@socket;" 2>/dev/null || echo "Server not running"
# Check server configuration file
sudo cat /etc/mysql/mysql.cnf
sudo cat /etc/mysql/mysql.conf.d/mysqld.cnf
sudo cat /etc/mysql/conf.d/*.cnf
sudo cat /etc/my.cnf
# Look for socket configuration lines:
# [mysqld]
# socket=/var/run/mysqld/mysqld.sock
# Check client configuration
sudo cat /etc/mysql/mysql.conf.d/mysql.cnf
# Look for client socket settings:
# [mysql]
# socket=/var/run/mysqld/mysqld.sock
# If socket paths don't match, edit config files to align them
sudo nano /etc/mysql/mysql.conf.d/mysqld.cnf
# Both should specify same socket path:
[mysqld]
socket=/var/run/mysqld/mysqld.sock
[client]
socket=/var/run/mysqld/mysqld.sock
# Restart MySQL to apply changes
sudo systemctl restart mysqlMismatched socket paths are a common cause of error 2002.
Test if MySQL works via network connection, which bypasses socket issues:
# Connect via TCP/IP (127.0.0.1) instead of socket (localhost)
mysql -h 127.0.0.1 -P 3306 -u root -p
# Specify the socket path explicitly
mysql -u root -p --socket=/var/run/mysqld/mysqld.sock
# Try alternate socket locations
mysql -u root -p --socket=/tmp/mysql.sock
mysql -u root -p --socket=/var/lib/mysql/mysql.sockIf connecting via 127.0.0.1 works but localhost fails, the issue is definitely socket-related. If 127.0.0.1 also fails, check if MySQL is actually running or if firewall is blocking port 3306.
A fresh restart often resolves socket-related issues:
# Stop MySQL completely
sudo systemctl stop mysql
# or
sudo service mysql stop
# Verify process is stopped
ps aux | grep mysqld # Should show no mysqld processes
# Check socket file is removed
ls -la /var/run/mysqld/mysqld.sock 2>/dev/null || echo "Socket removed (expected)"
# Start MySQL fresh
sudo systemctl start mysql
# Verify socket file is recreated
sleep 2 # Wait for socket to be created
ls -la /var/run/mysqld/mysqld.sock
# Test connection
mysql -u root -p
# If still fails, check logs immediately
sudo tail -20 /var/log/mysql/error.logWatch the error log closely during startup to catch any initialization errors.
Disk space issues prevent MySQL from creating the socket file:
# Check disk usage
df -h /var
df -h /tmp
df -h /var/run
df -h /var/lib/mysql
# Check available inodes
df -i /var
df -i /tmp
df -i /var/run
# If disk is full (0% available), free up space
du -sh /var/log/*
du -sh /var/cache/*
du -sh /tmp/*
# Clear old log files
sudo rm /var/log/mysql/*.gz # Remove compressed archives
sudo find /var/log -name "*.log.*" -delete # Old rotated logs
# Clear temp files
sudo rm -rf /tmp/*
# Clear package cache
sudo apt-get clean # Debian/Ubuntu
sudo yum clean all # CentOS/RHEL
# After freeing space, restart MySQL
sudo systemctl restart mysql
# Verify socket is created
ls -la /var/run/mysqld/mysqld.sockMake sure at least 1-2 GB is free on the filesystem containing /var.
If socket issues persist, a clean reinstall may be needed:
# Stop MySQL
sudo systemctl stop mysql
# Remove MySQL package (keep configuration/data backup first)
sudo mysqldump -u root -p --all-databases > ~/mysql_backup.sql
# Uninstall MySQL completely
sudo apt-get remove mysql-server mysql-client mysql-common # Debian/Ubuntu
sudo yum remove mysql-server mysql-client # CentOS/RHEL
# Remove data and configuration
sudo rm -rf /var/lib/mysql
sudo rm -rf /var/log/mysql
sudo rm -rf /etc/mysql
sudo userdel mysql
# Reinstall MySQL
sudo apt-get install mysql-server # Debian/Ubuntu
sudo yum install mysql-server # CentOS/RHEL
# Start fresh installation
sudo systemctl start mysql
# Run security script (recommended)
sudo mysql_secure_installation
# Restore data if needed
mysql -u root -p < ~/mysql_backup.sql
# Verify connection works
mysql -u root -pThis ensures all configuration files, permissions, and socket paths are properly initialized.
The ERROR 2002 has several advanced considerations:
1. Docker Socket Mapping: In Docker, MySQL socket file is often at /var/run/mysqld/mysqld.sock inside the container but not accessible from the host. Either use TCP/IP connection (127.0.0.1:3306) or mount the socket directory as a volume: -v mysql_socket:/var/run/mysqld.
2. Temporary File Cleanup: Linux systems often have automatic cleanup jobs (tmpwatch, systemd-tmpfiles) that delete old files from /tmp and /var/run. If MySQL socket is in /tmp, configure cleanup to preserve it or move socket to /var/run/mysqld instead.
3. SELinux and AppArmor: Security frameworks may block socket file creation. Check audit logs: sudo ausearch -m avc -ts recent | grep mysql (SELinux) or sudo dmesg | grep apparmor (AppArmor). These may need policy adjustments.
4. MySQL Cluster and Replication: Multiple MySQL instances require separate socket files (e.g., /tmp/mysql3306.sock, /tmp/mysql3307.sock). Ensure each instance uses unique socket path.
5. Cloud VMs and WSL2: Windows Subsystem for Linux (WSL2) and some cloud VM images have unusual /tmp or /var configurations. If socket path doesn't work, explicitly specify alternative: --socket=/home/user/mysql.sock and update my.cnf accordingly.
6. Socket File Recovery: If socket file is accidentally deleted while MySQL runs, restart MySQL to recreate it. If MySQL is hung, you may need to forcefully kill the process: sudo pkill -9 mysqld then restart.
7. Connection Pooling: Applications with connection pooling may not properly handle socket file disappearance. Ensure applications reconnect rather than keeping stale socket references.
8. Performance Comparison: Unix sockets are significantly faster than TCP/IP for local connections (lower latency, less overhead). Prefer sockets for local development, TCP/IP for remote/containerized deployments.
For persistent troubleshooting, enable MySQL error logging: set log_error=/var/log/mysql/error.log in my.cnf and monitor logs during connection attempts.
EE_WRITE (3): Error writing file
How to fix "EE_WRITE (3): Error writing file" in MySQL
CR_PARAMS_NOT_BOUND (2031): No data supplied for parameters
How to fix "CR_PARAMS_NOT_BOUND (2031): No data supplied for parameters" in MySQL
CR_DNS_SRV_LOOKUP_FAILED (2070): DNS SRV lookup failed
How to fix "CR_DNS_SRV_LOOKUP_FAILED (2070): DNS SRV lookup failed" in MySQL
ERROR 1146: Table 'database.table' doesn't exist
How to fix "ERROR 1146: Table doesn't exist" in MySQL
ERROR 1040: Too many connections
How to fix "ERROR 1040: Too many connections" in MySQL