The client cannot open a TCP connection to MariaDB or MySQL (error 2003)
ERROR 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.
Fix it fast
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'2Match what you see, then jump to its fix
- 1
ss prints nothing, and the service is inactive or failedThe server is not runningFix - 2
ss shows mariadbd on a port such as 3307, while the client dials 3306The client uses a different port than the serverFix - 3
Connection works from the server itself but is refused from another machineThe server is bound to another address than the one you dialFix - 4
The server listens on the right address, yet the port test from the client machine failsA firewall or network rule drops the connectionFix
- 1
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.service2Fix
Start the service. If it stops again, the journal or the error log names the reason; fix that first.
sudo systemctl start mariadb3Verify
mariadb-admin reports the server as up.
sudo mariadb-admin statusConfirmed by mariadb.com
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=tcp3Verify
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
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 33062Fix
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 mariadb3Verify
ss shows the server on the wider address, and the remote client connects.
sudo ss -ltn | grep 3306Confirmed by mariadb.com
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 33062Fix
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 tcp3Verify
The port test now connects and prints the server greeting.
telnet db.example.com 3306Confirmed by mariadb.com
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:
- TaxiDexMy own multi-tenant taxi dispatch SaaS: API, dispatcher portal, driver and passenger apps, and the servers underneath.
- QistLockA NestJS and React SaaS driving an Android Device Owner agent that locks financed phones when payments lapse.
- ShopGoAn e-commerce aggregator with a Python scraping engine behind its catalog, past 10K Google Play downloads.
Related fixes
Databases
The client cannot reach the MySQL or MariaDB server through its Unix socket file
ERROR 2002 (HY000): Can't connect to local server through socket '/run/mysqld/mysqld.sock' (2) (MariaDB client wording)
Error 2002 means the client tried the Unix socket file named in the message and found nothing it could talk to.
4 causes, each with a fixDatabases
Installing the Airflow MySQL provider fails on pkg-config or mysqlclient
Building the mysqlclient wheel fails during the install
The Airflow MySQL provider depends on mysqlclient, which pip compiles against the MySQL C client library.
2 causes, each with a fixDatabases
Compiling a C or C++ program that includes mysql.h fails
undefined reference to `mysql_init'
The compiler only finds mysql.h when the MySQL client development files are installed and their folder is on the include path.
3 causes, each with a fixDatabases
An EC2 instance cannot reach its RDS database
Could not open connection to the host, on port <port>: Connect failed
RDS denies all access until a security group allows it.
3 causes, each with a fixDatabases
Locked out of a fresh MariaDB install as root on Mac or Linux
ERROR 1045 (28000): Access denied for user 'root'@'localhost' (using password: NO)
A fresh MariaDB root account is not a normal password account.
3 causes, each with a fixDatabases
An Aria table fails with 'Read page with wrong checksum' (error 1030, code 176)
ERROR 1030 (HY000): Got error 176 "Read page with wrong checksum" from storage engine Aria
Code 176 means MariaDB's Aria engine read a data or index page whose checksum does not match, so that table file is damaged.
3 causes, each with a fix