MySQL Error 2003

Error number

2003

SQLSTATE

HY000

Symbol

CR_CONN_HOST_ERROR

Product

MySQL Server

Versions

MySQL client programs and libmysqlclient for MySQL 5.7, 8.0 and 8.4 (the 8.0 client shows host:port; the number in brackets is the operating system error)

Category

Connections & Network

Last reviewed

24 October 2026

What it means

Error 2003 means the client could not open a TCP/IP connection to the MySQL server at that host and port, so it never reached the login stage.

The mysql client and other programs built on libmysqlclient raise 2003 when the TCP connection itself fails. It happens before any user name or password is sent, so it is never a privilege problem: the server either is not listening at that address and port, or something on the network is stopping the connection. The message shows the host and port the client tried (127.0.0.1:3399), which is the first thing to check, because a wrong port or host in a configuration file is a very common cause.

The number in brackets is the operating system's socket error. 10061 on Windows and 111 on Linux mean the connection was refused: the host answered, but nothing accepts connections on that port (the server is stopped, listens on another port, or listens only on another interface). A timeout code (10060 on Windows, 110 on Linux) usually means a firewall or security group silently drops the packets, or the address is wrong. PHP mysqli and PDO report the same failure as 2002 with the operating system text, and an unknown host name is a different client error, 2005.

Common causes

• The MySQL server is not running on that host (stopped, crashed or still starting).
• The port is wrong: the server listens on a non-default port (3307, 3310 and so on), or the client uses the default 3306 and the server does not.
• The server listens only locally: bind_address is 127.0.0.1 or skip_networking is enabled, so remote clients are refused.
• A firewall, cloud security group or network ACL blocks the port between the client and the server (often a timeout rather than a refusal).
• A container port is not published, or the client inside a container uses localhost, which is the container itself rather than the database host.

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.

SHOW VARIABLES
WHERE Variable_name IN ('port', 'bind_address', 'skip_networking', 'admin_port', 'mysqlx_port');

SHOW GLOBAL STATUS LIKE 'Uptime';

SHOW GLOBAL STATUS LIKE 'Connection_errors%';

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.

-- From a command prompt:
-- mysql --no-defaults -h db.example.com -P 3306 -u app -p

Examples

Connecting to a port where no server listens

Run with the mysql 8.0.46 client on Windows. 10061 is the Windows code for a refused connection; on Linux the same situation shows 111.

-- From a command prompt (the server runs, but not on port 3399):
-- mysql -h 127.0.0.1 -P 3399 -u app -p
SELECT 1;

ERROR 2003 (HY000): Can't connect to MySQL server on '127.0.0.1:3399' (10061)

The same with the host name localhost

On Windows, localhost is a TCP/IP connection, so the error is 2003. On Linux and macOS, localhost makes the client use the Unix socket file instead, and a stopped server gives error 2002.

-- mysql -h localhost -P 3399 -u app -p
SELECT 1;

ERROR 2003 (HY000): Can't connect to MySQL server on 'localhost:3399' (10061)

A host name that does not resolve is a different error (2005)

When the name cannot be resolved, the client never tries to connect and reports 2005 (CR_UNKNOWN_HOST); 11001 is the Windows "host not found" code. Fix the host name or DNS, not the server.

-- mysql -h nosuchhost.invalid -u app -p
SELECT 1;

ERROR 2005 (HY000): Unknown MySQL server host 'nosuchhost.invalid' (11001)

How to prevent it

Keep the database host and port in one place in each application's configuration, and check them in a deployment health check that opens a real connection. Monitor that mysqld is running and alert on restarts (a falling Uptime), so clients do not discover an outage through 2003.

Decide the network exposure deliberately: listen on a private interface only, allow the port from known application hosts, and use SSH tunnels or a bastion for administration. For containers, publish the port and connect by the service name rather than localhost.

Common questions

Learn more on CodeWithSQL

• Install MySQL
• Run MySQL in Docker

Official documentation

• MySQL client error message reference
• Can't connect to [local] MySQL server
• Troubleshooting problems connecting to MySQL
• Server system variables (bind_address, port, skip_networking)

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.