ERROR 2003 (HY000): Can't connect to MySQL server on 'host'

What it means

Error 2003 comes from your client, not the server: it tried to open a TCP connection to the host and port you gave and didn’t get one. No user name or password has been checked yet.

The number in brackets is the operating system’s reason, and it tells you where to look:

On Windows the refused case is (10061).

Common causes

1. The server isn’t running, or it’s on a different port (Docker setups often publish the container’s 3306 on another port, such as 3307).
2. The server only listens on 127.0.0.1: bind_address is set to the loopback address, so connections from other machines are refused. skip_networking turns off TCP altogether.
3. A firewall or cloud security group drops the connection: the classic timeout. Hosted databases usually need your IP address on an allow-list.
4. The Docker port isn’t published. A container’s 3306 is only reachable from your Mac if it was started with -p (or ports: in Compose).
5. The wrong host: a typo, an old IP address, or a private address you can only reach through a VPN or a bastion host.

How to fix it

Test the port on its own

nc checks the TCP connection without any MySQL in the way:

nc -vz -G 3 <host> 3306

Connection to 127.0.0.1 port 33384 [tcp/*] succeeded!
nc: connectx to 127.0.0.1 port 3399 (tcp) failed: Connection refused
nc: connectx to 10.255.255.1 port 3306 (tcp) failed: Operation timed out

Refused: go to the server and check it’s running and which port it uses. Timed out: look at firewalls, security groups and the address itself.

Check the port and listening address on the server

On the server, or through any connection that works:

SELECT @@port, @@bind_address, @@skip_networking;

bind_address of 127.0.0.1 only accepts local connections; * (MySQL’s default) or 0.0.0.0 accepts them on every interface. MariaDB shows NULL when it isn’t set, which also means every interface. Change it in the server’s config file (bind-address under [mysqld]) and restart. Opening the server to the network also means checking its accounts and firewall rules.

Docker: check the published port

docker port <container>

3306/tcp -> 0.0.0.0:33384

Connect to 127.0.0.1 and the port on the right (33384 here). No output means nothing is published: recreate the container with -p 3306:3306.

Hosted databases

Add your current public IP address to the provider’s allow-list or security group, and check whether the instance has public access at all. If it’s private, connect through the provider’s bastion or a VPN, or use an SSH tunnel.

“Unknown MySQL server host”: error 2005

If the host name doesn’t resolve, you get a different number:

ERROR 2005 (HY000): Unknown MySQL server host 'db.invalid' (-2)

Check the spelling, and whether the name only resolves inside a VPN or a Docker network (a Compose service name such as db works from other containers, not from your Mac).

Reproduce it

With the mysql client from the MySQL 8.4.11 image, to a port nothing listens on:

mysql -h127.0.0.1 -P3399 -uroot -p -e 'select 1'

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

To an address that doesn’t answer, with a three-second timeout (--connect-timeout=3):

ERROR 2003 (HY000): Can't connect to MySQL server on '10.255.255.1:3306' (110)

The mariadb client from MariaDB 11.4.13 reports the same failures as 2002, without “MySQL” and without the port. A refused port shows (115), “operation now in progress”, rather than the real reason:

ERROR 2002 (HY000): Can't connect to server on '127.0.0.1' (115)
ERROR 2002 (HY000): Can't connect to server on '10.255.255.1' (110)

So with MariaDB’s client, a 2002 that names a host rather than a socket is this problem, not the socket one.

In Inlet

When Inlet can’t reach the server, the connection window shows the reason with a hint. If the database is only reachable from inside a private network, connect through an SSH tunnel: Inlet runs the system ssh, so your ~/.ssh/config, the SSH agent and the 1Password agent all work.