MySQL "ERROR 2003: Can't connect to MySQL server": read the number in brackets

1. Is the server running?

sudo systemctl status mysql
sudo journalctl -u mysql -n 30 --no-pager

The service is mysql on Ubuntu and Debian, mysqld on RHEL, and often mariadb. If it’s stopped, start it and read why it stopped: a full disk is a usual reason, and no space left on device covers that.

On Windows:

Get-Service *mysql*, *maria*
Test-NetConnection 10.0.0.5 -Port 3306

2. Refused: bind-address

Check the address it listens on:

sudo ss -tlnp | grep 3306

LISTEN 0  151  127.0.0.1:3306  0.0.0.0:*  users:(("mysqld",pid=812,fd=23))

127.0.0.1 is the default on Debian and Ubuntu, so connections from other machines are refused. Set the address in the config file:

• /etc/mysql/mysql.conf.d/mysqld.cnf on Ubuntu and Debian;
• /etc/mysql/mariadb.conf.d/50-server.cnf for MariaDB there;
• /etc/my.cnf or /etc/my.cnf.d/ on RHEL.

[mysqld]
bind-address = 10.0.0.5

Use the machine’s private address, or 0.0.0.0 for all of them. Then restart and check again:

sudo systemctl restart mysql
sudo ss -tlnp | grep 3306

If ss shows nothing while the service runs, look for skip_networking in the config: it turns off TCP completely. If the port isn’t 3306, a port setting has changed it:

mysql -e "SHOW VARIABLES WHERE Variable_name IN ('port','bind_address','skip_networking');"

3. Timed out: the firewall

Here the packets get dropped on the way. Test from the client, without MySQL involved:

nc -vz -w 5 10.0.0.5 3306

On the server, open the port only for the machines that need it:

# Ubuntu / Debian
sudo ufw allow from 10.0.0.20 to any port 3306 proto tcp

# RHEL / Rocky / AlmaLinux
sudo firewall-cmd --permanent --add-rich-rule='rule family="ipv4" source address="10.0.0.20" port port="3306" protocol="tcp" accept'
sudo firewall-cmd --reload

In the cloud, also check the security group or network firewall. They sit outside the machine, so the server never sees those packets. You can practice the difference between the two failures in the terminal, and “Connection timed out” vs “Connection refused” explains it in depth.

4. Docker

Inside a container, 127.0.0.1 is the container itself. That’s the classic reason for error 111 in a Compose project. Use the service’s name:

services:
  app:
    environment:
      DB_HOST: db      # not localhost
  db:
    image: mysql:8.4

Connecting from your computer instead? The port has to be published, with ports: ["127.0.0.1:3306:3306"]. A database also takes a while to start, so an app that connects right away fails once and then works: add a healthcheck. Connecting to localhost from a container goes through every combination.

5. It connects now: what’s next

Past this error, you might see the next layer:

ERROR 1130 (HY000): Host '10.0.0.20' is not allowed to connect to this MySQL server
ERROR 1045 (28000): Access denied for user 'app'@'10.0.0.20' (using password: YES)

Good news: the network works. Those are about accounts, and an account in MySQL is a user and a host. See MySQL error 1045.