Maaz Zindani

Loading the index…

↑↓ move↵ openesc close4072 pages
Databases and Redis

The client cannot open a TCP connection to MariaDB or MySQL (error 2003)

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

Short answer

Error 2003 means the client tried a TCP connection to the host and port and nobody answered. The number in brackets is the operating system's reason: 10061 on Windows and 111 on Linux both mean refused. The server may be stopped, listening on another port, bound to another address, or blocked by a firewall. Check what is actually listening first.

  • Applies to MariaDB 11.4 LTS, MySQL 8.4 LTS, Ubuntu 24.04, mariadb client 11.4
  • Updated
  • By Maaz Zindani, Senior Software Engineer

Fix it fast

  1. 1Find out which cause you have

    Ask the machine that runs the database whether anything is listening on a TCP port, and which port it is. No line in the output means the server is not up or has networking off.

    sudo ss -ltnp | grep -E 'mariadbd|mysqld'
  2. 2Match what you see, then jump to its fix

    1. 1ss prints nothing, and the service is inactive or failedThe server is not runningFix
    2. 2ss shows mariadbd on a port such as 3307, while the client dials 3306The client uses a different port than the serverFix
    3. 3Connection works from the server itself but is refused from another machineThe server is bound to another address than the one you dialFix
    4. 4The server listens on the right address, yet the port test from the client machine failsA firewall or network rule drops the connectionFix

What does the error look like?

  • ERROR 2003 (HY000): Can't connect to MySQL server on '127.0.0.1' (10061)
  • ERROR 2003 (HY000): Can't connect to MySQL server on '127.0.0.1:3306' (111)
  • ERROR 2003 (HY000): Can't connect to MySQL server on 'db.example.com' (115)

Cause 1 of 4

The server is not running

1Check

Ask the service manager, then read the last journal lines for the reason it stopped.

sudo systemctl status mariadb
sudo journalctl -n 30 -u mariadb.service

2Fix

Start the service. If it stops again, the journal or the error log names the reason; fix that first.

sudo systemctl start mariadb

3Verify

mariadb-admin reports the server as up.

sudo mariadb-admin status

Confirmed by mariadb.com

Did this fix it?

Cause 2 of 4

The client uses a different port than the server

1Check

Compare the port the server reports with the port in your client, app config or connection string.

sudo mariadb -e "SHOW VARIABLES LIKE 'port'"
grep -rn "^port" /etc/mysql/

2Fix

Make the client use the server's port, and force TCP so a socket is not tried instead.

mariadb -u someuser -p -h 127.0.0.1 --port=3307 --protocol=tcp

3Verify

The prompt opens, and the connection id shows in the status line.

mariadb -u someuser -p -h 127.0.0.1 --port=3307 -e "SELECT 1"

Confirmed by mariadb.com

Did this fix it?

Cause 3 of 4

The server is bound to another address than the one you dial

1Check

The server only accepts TCP on the addresses given in bind-address. Many distribution packages set it to 127.0.0.1, which refuses every remote client.

sudo mariadb -e "SHOW VARIABLES LIKE 'bind_address'"
sudo ss -ltn | grep 3306

2Fix

Set bind-address to the interface the clients use (or 0.0.0.0 for all), restart the server, and make sure the user account allows the client host.

# /etc/mysql/mariadb.conf.d/50-server.cnf
[mysqld]
bind-address = 0.0.0.0

sudo systemctl restart mariadb

3Verify

ss shows the server on the wider address, and the remote client connects.

sudo ss -ltn | grep 3306

Confirmed by mariadb.com

Did this fix it?

Cause 4 of 4

A firewall or network rule drops the connection

1Check

Test the port from the machine that cannot connect. A refusal there, while ss on the server looks correct, points at a firewall or network rule in between.

telnet db.example.com 3306

2Fix

Open the database port only to the client addresses that need it, in the host firewall and in any cloud security group.

sudo ufw allow from 203.0.113.10 to any port 3306 proto tcp

3Verify

The port test now connects and prints the server greeting.

telnet db.example.com 3306

Confirmed by mariadb.com

Did this fix it?

How do I stop it coming back?

  • Keep the port, host and protocol in one shared config value instead of copying them into each app.
  • Use 127.0.0.1 with the port when you mean TCP; localhost makes the client try a Unix socket first.
  • Never open 3306 to the whole internet; allow named client addresses or use an SSH tunnel.
  • Alert on the database service state so a stopped server is found before users are.

Sources

How was this page made?

I drafted this page with AI assistance from the official documents listed under Sources. Every cause above names the document that confirms it. I have not reproduced this fix on a machine of my own yet, so read it as documented guidance, not a test report. Found a mistake? Tell me.

Which stack is behind this page?

Projects of mine built on the same technologies:

Related fixes

Next step

Want this handled for good?

I look after servers, apps and releases end to end. Tell me what keeps breaking.