MySQL Error 2003: Can't Connect to MySQL Server

MySQL client Error 2003 (HY000, CR_CONN_HOST_ERROR) means the client could not connect to the specified MySQL host and port. A typical message is Can't connect to MySQL server on 'db.example.com:3306' (111). The number in parentheses is an operating-system error code and can vary by platform. See the MySQL 8.4 client error reference.

Start with the exact host, port, and connection protocol used by the application. Error 2003 usually occurs before MySQL can check the account password or privileges, so changing grants will not fix an unreachable server.

Check the host, port, and protocol

Confirm the database endpoint and port with the administrator or hosting provider. Port 3306 is the default for MySQL classic protocol, but installations can use another port. Then try the same connection parameters with the MySQL client, which prompts for the password rather than placing it in the command:

mysql --protocol=TCP \
  --host=db.example.com \
  --port=3306 \
  --user=app_user \
  --password \
  --connect-timeout=5

If the application runs in a container, localhost usually refers to that container, not the database server. Use the database’s reachable service name or private address. On the same Unix-like machine, localhost commonly uses a Unix socket; 127.0.0.1 with --protocol=TCP tests TCP/IP instead. Error 2002 is the separate client error for a local socket failure; see MySQL Error 2002 troubleshooting.

If the client reports Error 2005 (Unknown MySQL server host), troubleshoot DNS or the hostname separately; see MySQL Error 2005 troubleshooting.

Confirm that MySQL accepts TCP/IP connections

If you can connect locally or have an administrator who can, inspect the server’s network settings:

SHOW VARIABLES
WHERE Variable_name IN ('port', 'bind_address', 'skip_networking');

Check that the server is listening on the expected port and on an interface reachable from the client. If skip_networking is enabled, MySQL does not accept TCP/IP connections. If bind_address is set to 127.0.0.1, the server listens only on the local loopback interface and remote clients cannot reach it. Review the MySQL 8.4 documentation for bind_address, skip_networking, and connection troubleshooting.

Also confirm that the MySQL service is running and check its server log for startup or listener errors. If local connections work but remote connections fail, ask the administrator to verify the server’s private network route and the firewall or cloud security rule for the configured port.

Do not expose MySQL to every public IP address as a quick test. If remote access is required, restrict the listener and network rule to the approved private interface and application source, or use a VPN or SSH tunnel.

Error 2003 versus related connection errors

• Error 2003 (CR_CONN_HOST_ERROR): the client could not connect to the specified host and port.
• Error 2002 (CR_CONNECTION_ERROR): the client could not connect through a local socket; see MySQL Error 2002 troubleshooting.
• Error 2005 (CR_UNKNOWN_HOST): the client could not resolve the MySQL server hostname; see MySQL Error 2005 troubleshooting.
• Error 2006 (CR_SERVER_GONE_ERROR): the connection was lost or closed after it was established; see MySQL Error 2006 troubleshooting.
• Error 1130: the server replied that the client host is not allowed; see MySQL Error 1130.
• Error 1045: the server rejected account authentication; see MySQL Error 1045.

For other server and client errors, browse the MySQL error troubleshooting index.