MySQL error 2003 means your client reached for the database server and never got a working network connection. The full message reads “Can’t connect to MySQL server on” followed by a host, a port and a number in brackets. That number tells you why it failed.
I reproduced the error on MySQL 8.0.35 and WordPress 7.1.3 in October 2026, on a local test machine with two MySQL servers. I triggered it with a stopped server, a wrong port, a blocked address, bind-address and skip-networking, and I logged the exact output each time.
This guide explains what the error means and how to read the number in brackets. It then gives six checks in the order that fixes most cases fastest, plus the WordPress and PHP versions of the same failure.
What Is MySQL Error 2003?
MySQL error 2003 is a client error that says the connection to the server failed at the network level. The client found an address but could not open a TCP connection to it. No password was checked yet. The problem is the server, the port, the address or a firewall.
The MySQL connection troubleshooting guide uses this exact message as its first example. It shows ERROR 2003: Can't connect to MySQL server on 'host_name' (111) and says the server is not running or not reachable on that host and port.
A typical message from the command line client looks like this:
ERROR 2003 (HY000): Can't connect to MySQL server on '127.0.0.1:3307' (61)
Read it in three parts. The host and port inside the quotes show where the client tried to connect. The number at the end comes from the operating system and names the network failure.
People search for it as error 2003, MySQL 2003 error or “can’t connect to MySQL server”. They are all the same client error. The checks below apply to every one of them.
What the Number in Brackets Means
The number in brackets is the operating system’s network error code, and it splits error 2003 into two cases. A refused connection means nothing listens on that port. A timeout means something between you and the server drops the packets, which usually points to a firewall or a wrong address.
The codes differ by system, which confuses many readers. Linux uses 111 for refused, macOS uses 61, and Windows uses 10061. Microsoft’s Windows Sockets error codes list 10061 as connection refused and 10060 as connection timed out.

My test machine runs macOS. My refused connections ended in (61). A connection to an address that never answered waited five seconds and ended in (60), the macOS timeout code.

The third line in that test is a different error on purpose. A host name that does not exist returns error 2005, “Unknown MySQL server host”, with code 8. If you see 2005, fix the name in your settings before you look at anything else.
Common Causes of Error 2003
Error 2003 has a short list of causes, and my tests reproduced five of them on one machine. The server may be stopped, the port may be wrong, or the server may listen only on one address. Networking may be off entirely, or a firewall may block the port between the two machines.
- The server is stopped: A stopped MySQL service refuses every connection. You get the refused code.
- The wrong port: MySQL uses port 3306 by default, and a client that dials another port gets refused.
- A local-only bind address: With
bind-addressset to127.0.0.1, the server ignores connections from other machines. - Networking turned off: With
skip-networkingon, the server accepts no TCP connections at all. - A firewall: A blocked port usually produces a timeout code instead of a refused one.
The MySQL guide confirms the last three in its own words. It says a server started with skip_networking accepts no TCP/IP connections, and a server bound to 127.0.0.1 does not accept remote connections.
Cloud databases add one more layer. On a managed host or a cloud server, a security group or a remote access list can block the port. That happens even when the server and its settings are correct.
How to Fix MySQL Error 2003
To fix MySQL error 2003, work from the cheapest check to the hardest one. Read the bracket code first and then confirm the server runs and check the host and port. After that, check the bind address, networking and the firewall in that order and stop when the connection works.

1. Read the Bracket Code
Look at the number at the end of the message before you change anything. A refused code such as 111, 61 or 10061 means the server or port is wrong. A timeout code such as 110, 60 or 10060 means a firewall, a network route or a wrong IP address.
This one look decides where you spend the next ten minutes. Refused sends you to steps 2 to 5, while a timeout sends you straight to step 6.
2. Check That the MySQL Server Is Running
Ask the server to answer with mysqladmin ping. A running server replies “mysqld is alive”, and a stopped one returns error 2003 with the refused code. In my test, the stopped server also printed a useful hint naming the host and port to check.
mysqladmin -h 127.0.0.1 -P 3306 -u root -p ping
If the server is down, start it with your system’s service manager, for example sudo systemctl start mysql on most Linux servers. Then read the MySQL error log to learn why it stopped.
A full disk or a crashed table can stop MySQL again a minute after you start it. The log usually names the cause in its last few lines.
3. Confirm the Host and Port
Check that the port in the error matches the port the server listens on. List listening ports with lsof on macOS or ss -ltnp on Linux. In my test, the server listened on 127.0.0.1:3399, and every attempt on another port was refused.

The listening line shows both the address and the port. A line such as 127.0.0.1:3306 means local connections only, while *:3306 means the server accepts connections on every address.
If no MySQL line appears at all, the server is either stopped or running with networking off. Step 5 covers the second case.
4. Check the bind-address Setting
Open the MySQL configuration file, often /etc/mysql/mysql.conf.d/mysqld.cnf on Ubuntu, and find bind-address. A value of 127.0.0.1 accepts local connections only. Change it to the server’s own IP or to 0.0.0.0 and restart MySQL.
I tested this with a second server on port 3400. Bound to 127.0.0.1, it refused a connection from the machine’s own network address with error 2003. Bound to 0.0.0.0, the same command reached the server.

The second error in that test is good news. Error 1130 says the host is not allowed to connect. The network now works and only the user account blocks you.
Fix it by creating a user for the remote host, for example 'app'@'192.168.1.%', with only the rights the app needs. Avoid opening root to every host.
5. Turn Off skip-networking
Search the configuration for skip-networking and remove the line or comment it out. With it on, MySQL accepts socket connections only. Any TCP connection returns error 2003. In my test, @@skip_networking showed 1 and the socket still worked while every TCP attempt was refused.
This setting hides well because local tools often connect through the socket and keep working. A command line client on the same server looks fine while every application that uses TCP fails.
Restart MySQL after the change. Then run the ping from step 2 again with -h 127.0.0.1 to force a TCP connection.
6. Open the Firewall Port
If the bracket code is a timeout, check every firewall between the client and the server. That means the server’s own firewall, such as ufw or firewalld, a cloud security group and any network firewall. Allow port 3306 only from the addresses that need it.
On Ubuntu with ufw, a rule such as sudo ufw allow from 203.0.113.10 to any port 3306 opens the port to one client. Replace the example address with your application server’s address.
Never open port 3306 to the whole internet. A database that anyone can reach becomes a target for password guessing within hours.
MySQL Error 2003 in WordPress
WordPress shows MySQL error 2003 as “Error establishing a database connection”. The page hides the low-level error. The same screen can mean a wrong password, a wrong host or a stopped server. Turning on debug mode shows the network error and the host WordPress tried.
I changed DB_HOST in wp-config.php from the correct port to 127.0.0.1:3307 on my test site. The front end returned HTTP 500 with the standard message. With WP_DEBUG set to true, the page added “Connection refused” and the exact host.

The wp-config.php documentation shows the valid DB_HOST forms. You can add a port, as in 127.0.0.1:3307, or a socket path, as in localhost:/var/run/mysqld/mysqld.sock.
define( 'DB_HOST', 'localhost' ); define( 'DB_HOST', '127.0.0.1:3307' ); define( 'DB_HOST', 'localhost:/var/run/mysqld/mysqld.sock' );
Edit the file over FTP if the dashboard is down. Our guide on using FileZilla to edit site files shows how to download wp-config.php, change it and upload it again.
Turn debug display off again once you find the cause. Leaving it on shows file paths and database details to every visitor.
Why PHP Shows Error 2002 Instead of 2003
PHP often reports the same failure as error 2002 instead of 2003. In my test, the command line client printed 2003 for a refused port, while PHP’s PDO printed SQLSTATE[HY000] [2002] Connection refused for the same connection. Both point to the same cause and the same fixes.
The difference comes from the driver. Modern PHP uses its own MySQL driver, mysqlnd, which reports 2002 for refused and timed out connections. Older PHP builds linked to the MySQL client library reported 2003, which is why both versions appear in search results.

The host name changes the message too. With localhost, PHP skips TCP and looks for a socket file. My test returned “No such file or directory”. Use 127.0.0.1 to force TCP or set the correct socket path.
That is also the answer to a long PDOException that many people paste into search. A message such as PDOException: SQLSTATE[HY000] [2003] Can't connect to MySQL server on '10.1.12.123' (111) from a file named lock.inc comes from an older Drupal site. Code 111 means the server at that address refused the connection.
Error 2003 vs 2002, 2005, 1045 and 1130
Several MySQL errors look alike, but each one points to a different fix. Errors 2003 and 2002 are network failures, 2005 is a bad host name, and 1045 is a wrong password. Error 1130 means the network works and the user account does not allow your host.
Keep this table next to your logs.
| Error | Meaning | First fix |
|---|---|---|
| 2003 | TCP connection failed | Server, port, bind address and firewall |
| 2002 | Socket or TCP failure in PHP | Socket path or use 127.0.0.1 |
| 2005 | Unknown server host | Spelling of the host name |
| 1045 | Access denied | User name and password |
| 1130 | Host not allowed | Create a user for that host |
The order of these errors is also a progress bar. When 2003 turns into 1130 or 1045, the network part is fixed and only the account settings remain.
If you see a redirect loop instead of a database error after a move, that is a different problem. Our guide to the ERR_TOO_MANY_REDIRECTS error covers that case.
How to Prevent Error 2003
You prevent error 2003 by documenting the database host, port and bind address, and by monitoring the server. Most cases start after a change, such as a server move, an update or a new firewall rule. A short routine after each change catches the failure before your visitors do.
- Write down the connection details: Keep the host, port and socket path for every site in one place.
- Monitor the service: A simple uptime check that runs
mysqladmin pingwarns you when MySQL stops. - Watch disk space: A full disk is a common reason MySQL stops and refuses connections.
- Test after changes: Connect from the application server after every firewall or configuration change.
- Restrict access: Allow port 3306 only from known addresses, and use separate users per application.
A WordPress care plan covers uptime checks, backups and updates. A stopped database gets noticed in minutes. If you need help with a server that keeps failing, our WordPress maintenance services include database checks.
Conclusion
MySQL error 2003 always means the client could not open a network connection to the server. Read the number in brackets first, because refused and timed out connections need different fixes.
Then confirm the server runs, check the host and port, and look at bind-address and skip-networking. If the code is a timeout, open the firewall port for the client that needs it.
On WordPress, the same failure appears as “Error establishing a database connection”. Check DB_HOST in wp-config.php, and remember that PHP may report the same problem as error 2002.
Frequently Asked Questions (FAQs)
Q1. What does MySQL error 2003 mean?
It means the MySQL client could not open a TCP connection to the server at the host and port shown. The server may be stopped, listening elsewhere or blocked by a firewall. The number in brackets tells you whether the connection was refused or timed out.
Q2. What does (111) mean in error 2003?
Code 111 is the Linux code for connection refused. Nothing accepted the connection on that host and port. Check that MySQL runs and listens on the right address. On macOS the same failure shows 61 and on Windows it shows 10061.
Q3. What does “could not connect to MySQL, please check your database settings” mean?
Installers and apps show this message when their database connection fails. Check the host, port, database name, user and password in the app’s settings. If they are correct, run the six checks above, starting with the server status.
Q4. Should I use localhost or 127.0.0.1 in DB_HOST?
With localhost, PHP connects through a socket file, while 127.0.0.1 forces a TCP connection. If the socket path is wrong, localhost fails while 127.0.0.1 works. Use whichever your host documents, and add the socket path when needed.
Q5. How do I fix error 2003 on a remote MySQL server?
Check that MySQL listens on an address the client can reach, such as 0.0.0.0 or the server IP. Then open port 3306 in the server firewall and any cloud security group for the client’s address. Finally, create a user allowed to connect from that host.
Q6. Is error 2003 the same as “Error establishing a database connection”?
Not exactly. The WordPress message covers every database connection failure, including wrong passwords. Error 2003 is one specific network failure behind it, and turning on WP_DEBUG shows which one you have.
