MySQL Error 2002 (HY000) means your client can’t reach the MySQL server. The error appears in three slightly different forms depending on what you connected with:
The error code breakdown: 2002 = client-side connection error; HY000 = generic SQL state. (10061) on Windows means “connection actively refused” — the OS got there but nothing answered. (2) on Linux means “no such file” — the socket file is missing.
This guide walks 7 root causes in order of likelihood.
1. MySQL service isn’t running
This is the cause 90% of the time. Check + start:
2. Wrong port
MySQL defaults to 3306. If you (or your installer) changed it, your client needs to know:
On Windows: netstat -ano | findstr 3306 or check C:\ProgramData\MySQL\MySQL Server 8.0\my.ini for the port setting.
3. Socket file missing (Linux/Mac only)
On Linux + macOS, MySQL clients use a Unix socket by default for localhost connections (faster than TCP). If MySQL is running but the socket file is missing or in the wrong place, you get error 2002.
If the file is missing, MySQL didn’t fully start (check the service status from step 1). If it’s in a non-default location, point your client there:
mysql -u root -p --socket=/tmp/mysql.sockOr force TCP to sidestep sockets entirely:
mysql -h 127.0.0.1 -P 3306 -u root -p4. Firewall blocking the port
Mostly relevant if connecting from another machine, or if you’re on a corporate / antivirus-restricted Windows machine.
On Linux:
sudo ufw allow 3306/tcp5. bind-address restricting connections
In my.cnf / my.ini, the bind-address directive limits which interfaces MySQL listens on. Common gotcha: setting it to 127.0.0.1 blocks every connection except from the same machine.
To accept connections from other machines, change to 0.0.0.0 (any interface) or your specific network IP, then restart MySQL.
6. Wrong credentials cached
You can also get error 2002 in some edge cases where the client uses a cached connection profile pointing at the wrong host. Easy diagnostic: explicitly pass everything on the command line:
If this works but mysql -u root -p alone fails, your local ~/.my.cnf or [client] section in /etc/mysql/my.cnf has a stale setting. Check and update.
7. MySQL didn’t fully start
Check the error log for crash reasons:
On Windows: check C:\ProgramData\MySQL\MySQL Server 8.0\Data\<hostname>.err.
Common causes the log will reveal: disk full, corrupted InnoDB tables, port already in use by another process, missing data directory.
Quick reference
| Cause | Fast diagnostic | Fix |
|---|---|---|
| Service not running | sc query MySQL80 (Win), brew services list (Mac), systemctl status mysql (Linux) | Start it |
| Wrong port | netstat -tlnp | grep mysql | Pass -P <port> |
| Socket file missing | ls /var/run/mysqld/mysqld.sock | Use -h 127.0.0.1 to force TCP |
| Firewall blocking | Try connecting from same machine first | Allow port 3306 |
bind-address limit | grep bind-address my.cnf | Change to 0.0.0.0 if needed |
| Cached profile | mysql -h 127.0.0.1 --protocol=TCP works but mysql doesn’t | Clean ~/.my.cnf |
| Service crashed | tail /var/log/mysql/error.log | Resolve whatever the log says |
Conclusion
Error 2002 always means “client can’t reach server” — but the reason varies. Walk the 7 causes in order:
- Service running? (90% of cases)
- Right port?
- Socket file present? (Linux/Mac)
- Firewall open?
bind-addressnot blocking?- No cached bad profile?
- What does the error log say?
The first 3 cover almost every case in dev environments. The last 4 matter more for shared/server setups.