MySQL Error 2002: Can't Connect Through Socket

MySQL client Error 2002 (HY000, CR_CONNECTION_ERROR) means the client could not connect to a local MySQL server through the named socket. A typical message is Can't connect to local MySQL server through socket '/tmp/mysql.sock' (2). The exact socket path and operating-system code vary by installation. See the MySQL 8.4 client error reference.

On Unix and Unix-like systems, local MySQL clients commonly use a Unix socket file. The server and client must agree on its path, and the MySQL service must be running. Windows clients can use named pipes, but pipe failures have different client error messages; see the MySQL guide to connection transport protocols and client error reference.

Confirm that the MySQL service is running

Check the MySQL service and its error log using the service manager and installation method for your system. If the server failed to start, fix the startup error first; a missing socket file is often a symptom rather than the cause. The MySQL guide to connecting to and disconnecting from a server notes that Error 2002 can occur when the server daemon or service is not running.

If MySQL is running, confirm that it created the socket at the path shown in the error. Do not remove a socket file or change its permissions until you have verified that no running MySQL server is using it.

Match the client and server socket paths

If you can connect to the same server over TCP, ask the server for its configured socket path:

SHOW VARIABLES LIKE 'socket';

Otherwise, check the server and client option files and the MySQL service startup options. The server’s socket setting specifies the local socket path. A client can use a different path from its --socket option, option file, or MYSQL_UNIX_PORT environment variable; see the MySQL 8.4 documentation for the server socket variable, the client --socket option, and MySQL environment variables.

When you know the correct path, test it explicitly:

mysql --protocol=SOCKET \
  --socket=/path/to/mysql.sock \
  --user=app_user \
  --password

The client prompts for the password. If the socket exists but the client reports a permission error, ask the system administrator to check directory traversal and socket ownership for the MySQL service and client user. Avoid making the socket or its parent directory world-writable.

Test TCP/IP separately

To check whether the server accepts TCP/IP on the local machine, use an explicit TCP connection:

mysql --protocol=TCP \
  --host=127.0.0.1 \
  --port=3306 \
  --user=app_user \
  --password \
  --connect-timeout=5

If TCP works but the socket connection fails, focus on the socket path and permissions. If TCP returns Error 2003, check whether MySQL is listening on the expected port and interface; see MySQL Error 2003 troubleshooting. For remote connections that reach MySQL but are rejected because of the client host, see MySQL Error 1130.

Error 2002 versus Error 2003

• Error 2002 (CR_CONNECTION_ERROR): the client could not connect to a local MySQL server through its configured socket file.
• Error 2003 (CR_CONN_HOST_ERROR): the client could not establish a TCP/IP connection to the specified MySQL host and port.

For other connection, authentication, and SQL failures, browse the MySQL error troubleshooting index.