The client cannot reach the MySQL server at the specified host and port, so the connection fails before any SQL runs.
MySQL Error 2003: CR_CONN_HOST_ERROR means the client cannot reach the MySQL server at the requested host and port. Verify network reachability, firewall rules, server listening on the correct port, and client credentials. Opening the port or using 127.0.0.1:3306 typically resolves the issue.
Can't connect to MySQL server on '%s:%u' (%d)
The error message "Can't connect to MySQL server on 'host:port' (2003)" tells the client library that the TCP handshake with the MySQL server failed.
No SQL is sent because the socket cannot open, so authentication never begins.
Developers see this code on CLI tools, application logs, and GUI connectors whenever the target host is offline, blocked, or mis-configured.
The error appears during the initial connection phase, usually right after DNS resolution and before the client sends the MySQL handshake packet.
Local, container, VPN, and cloud environments all trigger the issue when networking is broken.
It is common after server restarts, firewall changes, and incorrect connection strings in .env files or ORM configs.
Most failures relate to unreachable hosts, closed ports, or MySQL not listening on the expected interface. Firewalls, SELinux, or cloud security groups can block port 3306. Typos in hostnames or IPs lead to DNS lookup failures.
A server daemon stopped or bound to 127.0.0.1 only rejects external clients.
Ping the host to confirm network reachability. Run nc -zv host 3306 or telnet host 3306 to test the TCP port. If closed, open it in the firewall or cloud rule. Ensure mysqld is running and bind_address in my.cnf is 0.0.0.0 or the correct IP.
Update connection strings to use the right host, port, and protocol.
After the port is open, run mysql -h host -P 3306 -u user -p. A successful login confirms the fix.
Docker compose: expose "3306:3306" and use "host.docker.internal" inside containers. AWS RDS: add the client IP to the security-group ingress rule.
Localhost: specify 127.0.0.1 instead of "localhost" to force TCP when the socket file is missing.
VPN split-tunnel: disable split or add the database subnet to the tunnel so traffic reaches the server.
Automate health-checks that open a TCP socket before running migrations. Store host, port, and credentials in environment-specific secrets managers to avoid typos.
Use monitoring to alert on mysqld process downs and firewall drift.
In CI/CD, run integration tests against a containerized MySQL that exposes 3306 to ensure connection parameters stay valid.
Galaxy’s desktop SQL editor validates connection details before saving them. If port 3306 is unreachable, Galaxy flags the issue with actionable tips.
Shared connection profiles prevent teammates from re-entering bad hosts, and audit logs track credential edits to stop silent mis-configurations.
Error 2005 (CR_UNKNOWN_HOST) signals DNS lookup failure rather than TCP refusal. Error 2002 (CR_SOCKET_CREATE) occurs when the Unix socket file is missing. Error 1045 (ER_ACCESS_DENIED_ERROR) means the client reached the server but failed authentication.
The troubleshooting flow is similar: verify host, then port, then credentials.
.
Not always. The server might be up but firewalled or bound to a different interface.
TCP port 3306 is the default. Custom deployments may use another port specified in my.cnf.
You can correct client host and port typos, but network or mysqld changes require server-side access.
Galaxy tests the connection string on save, highlights unreachable hosts, and lets teams share verified profiles.
.avif)
.avif){kind=logo}
