MySQL "ERROR 2002 (HY000): Can't connect ... through socket" in CI
By Daniel Zoghalchali·Latchkey
The MySQL client fell back to a local Unix socket (e.g. /var/run/mysqld/mysqld.sock) that does not exist on the runner because MySQL is a separate container reachable over TCP. The socket file is absent, so the connect fails with ERROR 2002.
What this error means
mysql or a migration tool fails with "ERROR 2002 (HY000): Can't connect to local MySQL server through socket". It happens when the host is localhost (which triggers a socket connection) instead of 127.0.0.1 (which forces TCP).
mysql
ERROR 2002 (HY000): Can't connect to local MySQL server through socket
'/var/run/mysqld/mysqld.sock' (2)
Common causes
localhost forces a socket connection
With the MySQL client, localhost means "use the Unix socket". In CI the database is a TCP service, so there is no local socket to use.
Service not ready yet
If you do connect over TCP, the container may still be starting, which is transient and clears on retry.
How to fix it
Force TCP with 127.0.0.1
Use 127.0.0.1 (or --protocol=TCP) so the client connects over the network instead of a missing socket.
Use 127.0.0.1/--protocol=TCP for MySQL in CI, never localhost.
Gate the connection on a readiness check.
On managed runners (Latchkey), self-healing auto-retries genuinely transient connection failures while the database finishes starting.
Frequently asked questions
What causes ""ERROR 2002: Can't connect through socket""?
With the MySQL client, localhost means "use the Unix socket". In CI the database is a TCP service, so there is no local socket to use.
How do I fix "ERROR 2002: Can't connect through socket"?
Use 127.0.0.1 (or --protocol=TCP) so the client connects over the network instead of a missing socket.
Can Latchkey fix this automatically?
Yes. Latchkey runs your GitHub Actions on managed runners that detect this failure, apply the fix, and retry the job automatically - self-healing is on by default.
