Australian cloud for business software — built and run in Sydney since 2002

NetLeverage
NetLeverage

MySQL ERROR 2002 "Can't connect to local MySQL server through socket": is it running, and which socket

Technical article
Troubleshooting

About this article: This article is reviewed against the cited sources. This is source research, not lab validation. Check the stated versions and your own requirements before making changes.

ERROR 2002: Can't connect to local MySQL server through socket '/tmp/mysql.sock' (2) means the mysql client tried to reach the server through a Unix socket file and failed. The manual says error 2002 "normally means that there is no MySQL server running on the system or that you are using an incorrect Unix socket file name or TCP/IP port number when trying to connect to the server". Find out whether mysqld is running first, then whether the client and the server agree on the socket path.

What the error means

The MySQL 8.4 error reference lists error 2002, symbol CR_CONNECTION_ERROR, with the message Can't connect to local MySQL server through socket '%s' (%d). The first value is the socket path the client used. The number is the operating system error code.

The manual explains how a client picks a route on Unix: "A Unix socket file is used if you do not specify a host name or if you specify the special host name localhost." The default socket is /tmp/mysql.sock, though "For some distribution formats, the directory might be different, such as /var/lib/mysql for RPMs". The server's own setting is the socket system variable, whose default is /tmp/mysql.sock.

The code in brackets is an operating system error number. In the Linux kernel headers, ENOENT is 2 ("No such file or directory"), EACCES is 13 ("Permission denied") and ECONNREFUSED is 111 ("Connection refused"). Reading the code narrows the cause:

  • (2): the socket file does not exist at that path. The server is not running, or it put its socket somewhere else, or something removed the file.
  • (13): the file or its directory cannot be accessed by this account.
  • (111): the path exists but nothing accepted the connection.

Treat that mapping as guidance. The manual does not say which code goes with which cause, so confirm with the checks below.

Error 2003, Can't connect to MySQL server on 'server' (10061), is a network connection that was refused. It points at the port, bind_address, skip_networking or a firewall, not at the socket file.

Likely causes

Cause What you see How to confirm
mysqld is not running (2) or (111) Service status; the process list
Client and server use different socket paths The path in the message is not the server's socket value Compare the path in the message with the server's configuration
Socket file removed (for example by a job cleaning /tmp) (2) while the server is running The manual's example: a cron job that removes old files from /tmp
Permissions on the socket or its directory (13) ls -l on the socket and each directory above it
Server died and left a stale socket (111) Service status, error log
SELinux blocking access Permission-type errors despite correct modes The manual points to its SELinux section

Prove the cause before changing anything

All of these are read-only.

1. Read the path and the code in the message. Write them down.

2. Is the service running? The manual's systemd page names the unit files: mysqld.service on RPM platforms and mysql.service on Debian platforms. Check the one for your platform:

systemctl status mysql.service

If the server is not running, read the server's error log; the manual says the error log "contains a record of mysqld startup and shutdown times" and diagnostic messages.

3. Is anything listening on a Unix socket?

ss -xl

The ss page documents -x (Unix domain sockets) and -l (listening sockets). Look for a mysql socket path. The manual's own tool for the same question is netstat -ln | grep mysql.

4. Ask the server over a different route. Try TCP on the same host, which the manual describes: "You can also try -h 127.0.0.1 to connect with TCP/IP to the local host."

mysqladmin -h 127.0.0.1 version

If this works, the server is running and the socket path is the problem. The manual's description of mysqladmin ping says its return status is 0 if the server is running, "even in case of an error such as Access denied", because that error shows the server is running but refused the connection. So an access-denied error from a mysqladmin command does not mean the server is down. If the server was started with skip_networking enabled, TCP will fail even though the server runs. Once connected, ask it where the socket is:

SHOW GLOBAL VARIABLES LIKE 'socket';

5. Try the socket the server uses. The manual's form is:

mysqladmin --protocol=SOCKET --socket=/tmp/mysql.sock version

Replace the path with the one the server reported. If this works and a plain mysql does not, the client is looking at the wrong path.

6. Check the file and directory. ls -l on the socket and its directory. The manual says the server or client may not "have the proper access privileges for the directory that holds the Unix socket file or the socket file itself".

Fix

Server not running

Read the error log before you start it, so you know why it stopped. If it stopped after a crash, read "MySQL will not start after a crash: InnoDB errors and innodb_force_recovery used safely" rather than starting it repeatedly. Disruptive step: starting the server makes it available to clients and starts recovery work. After a configuration change, check the startup configuration first with mysqld --validate-config, which the manual says ends with exit code 0 if no errors are found. Run it as the operating system account that normally runs the server: the manual's password-reset page warns that starting mysqld as root without --user=mysql may create root-owned files in the data directory, and the configuration-validation page does not say whether the validation run can do the same. Start with the service manager, for example systemctl start mysql.service. To back out, stop it with systemctl stop mysql.service.

Client uses the wrong socket

Tell the client the path the server uses. The manual's options are a --socket option on each client program, the MYSQL_UNIX_PORT environment variable, or a [client] section in an option file with socket=/path/to/socket. For an option file, save first. Check whether the file exists with ls -l /etc/my.cnf; the path is the manual's example and your system may use another file.

cp /etc/my.cnf /etc/my.cnf.saved-20261120

If ls reports that /etc/my.cnf does not exist, there is nothing to copy; the file you create in the next step is then the new file, and the back-out below is to remove it.

Disruptive step: adding a socket line to the option file changes it for every client program on the host, because the file is read by all of them, so a wrong path breaks them all. Then add under [client] a line socket=/var/lib/mysql/mysql.sock (use the path the server reported). The manual's example puts the same value under [mysqld] and [client]. To back out, run cp /etc/my.cnf.saved-20261120 /etc/my.cnf and run the client again to confirm it behaves as it did before. If /etc/my.cnf did not exist before, back out by removing the file you created (rm /etc/my.cnf) and run the client again.

Socket removed from /tmp

The manual says the fix is to change the job so that it does not remove mysql.sock, or to move the socket file elsewhere. It also describes setting the sticky bit on /tmp so that files can be deleted only by their owners or the superuser, with chmod +t /tmp. Record the current mode first:

stat -c '%A %n' /tmp

The stat page documents %A (permission bits in human-readable form) and %n (file name); the manual says the sticky bit is set if the last permission character is t. If the recorded mode already ends in t, the bit is set and there is nothing to change. If it does not: Risk: chmod +t /tmp changes the mode of /tmp for every user and program on the host. Then run chmod +t /tmp. To back out, remove the bit with chmod -t /tmp (the chmod page documents t as the sticky-bit letter and - as the operator that removes a bit), which restores the mode you recorded. Never run the back-out when the recorded mode already ended in t.

To move the socket instead, first print the current value with SHOW GLOBAL VARIABLES LIKE 'socket'; and copy the option file as in the previous section. Disruptive step: moving the socket means changing socket for the server and clients and restarting the server, which disconnects users. In the option file, add socket=/var/lib/mysql/mysql.sock under both [mysqld] and [client], using the path you chose, check the startup configuration with mysqld --validate-config (run as the server's account), then restart the server. To back out, restore the copied option file with cp (or, if the file did not exist before, remove the one you created), run mysqld --validate-config again, and restart the server.

Permissions

The manual says to restart mysqld with a --socket option naming a file in a directory where both the server and the client accounts can reach the file. Record modes first with ls -l. Risk: changing the access on a directory changes it for every account and program that uses the directory. Then correct the access on the socket's directory or choose such a directory. To back out, set the modes you recorded back with chmod, then run the client again.

Example (illustrative): On db01, an administrator moves the socket to /var/lib/mysql/mysql.sock by setting socket under [mysqld] and restarting. Afterwards mysql fails with Can't connect to local MySQL server through socket '/tmp/mysql.sock' (2). mysqladmin -h 127.0.0.1 version works and SHOW GLOBAL VARIABLES LIKE 'socket'; reports the new path. The administrator saves /etc/my.cnf, adds socket=/var/lib/mysql/mysql.sock under [client], and mysql connects again.

Confirm the fix

  1. mysql connects without a --socket option.
  2. mysqladmin --protocol=SOCKET --socket=<path> version works for the configured path (write the real path).
  3. Applications on the host that use the socket connect, including ones with their own option files.
  4. The error no longer appears after the next restart of the server.

What to watch afterwards

  • Monitor the service and a local connection test, not only the process.
  • After moving a socket, update every client configuration and script that names the old path.
  • Keep the socket out of directories that a cleanup job touches.
  • Alert on server restarts and read the error log after each.

Risks and limits

  • These commands have not been run or lab-tested. They come from the MySQL 8.4 manual and Linux man pages.
  • The MySQL manual does not map the code in brackets to a cause; the mapping above comes from the errno names.
  • Unit names and option file paths differ between distributions.
  • MySQL 8.4 only. MariaDB is not covered. SELinux contexts are not covered.

Sources