- Error number
- 2002
- SQLSTATE
HY000- Symbol
CR_CONNECTION_ERROR- Product
- MySQL Server
- Versions
- MySQL client programs and libmysqlclient (Unix socket connections) for MySQL 5.7, 8.0 and 8.4; PHP mysqli and PDO_MYSQL (mysqlnd) for any failed connection
- Category
- Connections & Network
- Last reviewed
- 24 October 2026
On this page
What it means
Error 2002 means the client could not reach a MySQL server: for the mysql client, through the local Unix socket file; for PHP mysqli and PDO, by any route, including a refused TCP port or an unknown host.
On Linux and macOS, MySQL client programs connect through a Unix socket file when you give no host or the host localhost, and through TCP/IP for any other host, including 127.0.0.1. Error 2002 is the socket case: the client found no server behind the socket path it used (/tmp/mysql.sock in the manual's example; distributions often use paths such as /var/run/mysqld/mysqld.sock). The number in brackets is the operating system error: 2 means the socket file does not exist, 111 that it exists but nothing is accepting connections. The TCP/IP counterpart in the mysql client is 2003.
PHP is different. The mysqlnd driver behind mysqli and PDO_MYSQL reports every failed connection attempt as 2002 and puts the operating system's text after the number. In our runs a refused TCP port gave "No connection could be made because the target machine actively refused it" (where the mysql client said 2003), and an unknown host gave a getaddrinfo message (where the mysql client said 2005). So with PHP, the text after [2002] tells you which problem you have.
Common causes
- The MySQL server is not running, so the socket file is missing (error 2) or no process accepts connections on it (111).
- The client looks for the socket in a different place than the server created it: the server was started with another
--socketpath, or the client and server come from different packages with different defaults. - The socket file was deleted while the server was running, for example by a job that cleans /tmp, or the client has no permission to the socket directory.
- PHP connects to a host and port where nothing listens, or a firewall refuses the connection: mysqlnd reports this as 2002 with the operating system text.
- PHP cannot resolve the host name in the connection settings (a typo, a missing DNS entry, or a container service name used outside the container network).
Diagnose it
Read-only These statements only read metadata (information_schema, performance_schema and SHOW statements) or your own data. They do not change data, privileges or configuration, so they are safe to run first.
Where does the server put its socket, and is TCP/IP enabled?
Run this on the server through any connection that works (for example mysql -h 127.0.0.1, which uses TCP/IP), then compare the socket path with the one in the error.
SHOW VARIABLES
WHERE Variable_name IN ('socket', 'port', 'bind_address', 'skip_networking', 'named_pipe');socket is the path the server listens on (on Windows it is the named pipe name, MySQL by default, used only when named_pipe is ON). If it differs from the path in the error, point the client at it. skip_networking ON means only local socket connections are possible.
Did the server restart, and when?
SHOW GLOBAL STATUS LIKE 'Uptime';A short uptime matching the time of the errors means the server was down or restarting when the clients tried to connect. The error log says why.
Check the process and the socket from the operating system
On the server host, outside MySQL: ps xa | grep mysqld shows whether the server process runs, netstat -ln | grep mysql lists the socket file and port it listens on, and mysqladmin --protocol=SOCKET --socket=/tmp/mysql.sock version (with your path) tests that exact socket. These are the checks the MySQL manual gives for this error.
SHOW VARIABLES LIKE 'pid_file';The server's process id file. If the server is not running, the socket and this file are usually missing too.
How to fix it
Each fix is labelled with what it changes. Try read-only checks and the least invasive fix first, and test changes outside production.
Start the server if it is not running
Changes database stateStart the service (for example systemctl start mysqld, or mysql on some distributions) and read the error log to see why it stopped. A server that cannot start because of a configuration or disk problem will keep producing 2002 until that is fixed.
Point the client at the socket the server really uses
Client or network sideGive the path from SHOW VARIABLES LIKE 'socket' on the command line, or put it in the [client] section of the option file so every client program uses it. If you change the server's socket, change the clients too.
-- mysql --socket=/var/lib/mysql/mysql.sock -u app -p
# my.cnf
[client]
socket = /var/lib/mysql/mysql.sockUse TCP/IP explicitly
Client or network sideConnecting to 127.0.0.1 instead of localhost makes the client use TCP/IP, which bypasses the socket file altogether. This is also the usual answer inside containers, where the database runs in another container: connect to its service name and port.
-- mysql -h 127.0.0.1 -P 3306 -u app -p
-- PHP PDO
-- new PDO('mysql:host=127.0.0.1;port=3306;dbname=shop', 'app', $password);For PHP, fix the host, port or name the message describes
Client or network side"Actively refused" means the host is reachable but nothing listens on that port: check the port and whether the server accepts network connections, as for error 2003. A getaddrinfo message means the host name does not resolve: correct it or the DNS entry. Neither is solved by changing MySQL accounts or passwords.
Examples
The mysql client with the server stopped (Unix socket)
Shown as documented in the MySQL reference manual (Troubleshooting Problems Connecting to MySQL); not reproduced here, because the lab runs on Windows, which has no Unix socket connections.
-- On Linux, with mysqld not running:
-- mysql -u app -p
SELECT 1;ERROR 2002 (HY000): Can't connect to local MySQL server through socket '/tmp/mysql.sock' (111)
PHP PDO connecting to a port where nothing listens
Captured with PHP 8.2 PDO_MYSQL (mysqlnd) on Windows against MySQL 8.0.46's machine; mysqli gave the same connect_errno 2002 and text. The mysql client reports this situation as ERROR 2003 (HY000): Can't connect to MySQL server on '127.0.0.1:3399' (10061). The error lab compares mysql client output only, so this one is not rerun automatically.
<?php
// Nothing listens on port 3399 of this machine
$pdo = new PDO('mysql:host=127.0.0.1;port=3399;dbname=shop', 'app', $password);SQLSTATE[HY000] [2002] No connection could be made because the target machine actively refused it
PHP PDO with a host name that does not resolve
Captured with PHP 8.2 PDO_MYSQL (mysqlnd) on Windows; the text after [2002] comes from the operating system. The mysql client reports an unknown host as error 2005 instead.
<?php
$pdo = new PDO('mysql:host=nosuchhost.invalid;port=3306;dbname=shop', 'app', $password);SQLSTATE[HY000] [2002] php_network_getaddresses: getaddrinfo for nosuchhost.invalid failed: No such host is known.
Windows: the local named pipe is not enabled (error 2017)
On Windows the local alternative to TCP/IP is a named pipe rather than a socket file. With named_pipe OFF (the default, as on this server) the mysql 8.0.46 client reports 2017, not 2002. Connect over TCP/IP instead, or enable named_pipe on the server.
-- mysql --protocol=PIPE -h 127.0.0.1 -u app -p
SELECT 1;ERROR 2017 (HY000): Can't open named pipe to host: 127.0.0.1 pipe: MySQL (2)
Reproduced on MySQL 8.0.46, 24 October 2026.
How to prevent it
Be explicit about the transport. On the database host, either use the socket path the server reports in every client's option file, or connect to 127.0.0.1 so the socket path does not matter. Keep the socket out of directories that cleanup jobs empty, and monitor that mysqld is running so a stopped server is noticed before users see 2002.
In PHP applications, log the full message, not just the number: for mysqlnd, 2002 covers a stopped server, a wrong port, a firewall and a DNS failure, and the text is what tells them apart. Test the connection settings in each environment (host, port, socket) as part of deployment.
Common questions
Why does localhost fail with 2002 but 127.0.0.1 works?
On Unix, MySQL client programs treat localhost as "use the Unix socket file" and 127.0.0.1 as "use TCP/IP". If the client looks for the socket in the wrong place, localhost fails while 127.0.0.1 reaches the server over TCP. Point the client at the right socket, or keep using 127.0.0.1.
Why does PHP say 2002 when the mysql client says 2003?
They use different client libraries. The mysql client (libmysqlclient) has separate errors for the socket (2002), TCP/IP (2003) and unknown hosts (2005). PHP's mysqlnd reports a failed connection as 2002 and adds the operating system text, such as "actively refused" or a getaddrinfo failure.
What do (2) and (111) mean after the socket path?
They are operating system errors. 2 means the socket file does not exist, which usually means the server is not running or uses another path. 111 means the file exists but nothing accepts connections on it, typically a server that stopped without removing its socket.
Learn more on CodeWithSQL
Official documentation
- MySQL client error message reference
- Can't connect to [local] MySQL server
- Troubleshooting problems connecting to MySQL
Last technically reviewed 24 October 2026; examples and diagnostics run on MySQL 8.0.46. Message templates checked against the server's error catalogue (perror) for that version.