When Data Management (DMS) or a MySQL client fails to connect to a PolarDB for MySQL cluster, the cause is almost always one of four things: IP whitelist, database account permissions, wrong endpoint type, or a network-type mismatch between your ECS instance and the cluster.
IP whitelist not configured or incorrectly configured
Cause
The cluster blocks connections when the client IP address is not in the whitelist. Common root causes:
The default whitelist contains only
127.0.0.1, which blocks all external access.The client IP address was not added to the whitelist.
The IP address format in the whitelist is invalid (for example,
0.0.0.0instead of0.0.0.0/0).The IP address in the whitelist is not the actual outbound IP address of the client.
Solution
Find the outbound IP address of your client machine and add it to the cluster whitelist. For steps, see Configure an IP whitelist.
Use the correct CIDR format for IP ranges. For example, use
0.0.0.0/0to allow all IP addresses, not0.0.0.0.
For additional whitelist troubleshooting, see Troubleshoot IP whitelist issues.
No database account or insufficient permissions
Cause
The connection is rejected at the authentication layer. This happens when:
No database account exists on the cluster.
The account exists but does not have permission to access the target database.
Solution
If no account exists, create one and grant it the necessary database permissions. For steps, see Create a database account.
If the account exists but access is denied, update its permissions:
For a privileged account: Reset permissions of the privileged account
For a standard account: Modify the permissions of a standard account
Wrong endpoint type used
Cause
PolarDB clusters have two endpoint types — private and public — and using the wrong one for the network environment prevents connection.
Solution
Use the endpoint that matches how your client connects:
| Connection method | Endpoint to use |
|---|---|
| Over a virtual private cloud (VPC) | Private endpoint |
| Over the Internet | Public endpoint |
To find your cluster's endpoints, go to the cluster details page in the PolarDB console.
Network type mismatch between ECS and PolarDB
Cause
Your Elastic Compute Service (ECS) instance is on the classic network, but your PolarDB cluster is in a virtual private cloud (VPC). Instances on different network types cannot communicate directly.
Solution
Choose one of the following options:
Migrate the ECS instance to a VPC (recommended): After migration, place the ECS instance in the same VPC as the PolarDB cluster. For steps, see Migrate ECS instances from a classic network to a VPC.
The ECS instance and the PolarDB cluster must be in the same VPC. Placing them in different VPCs does not resolve the connectivity issue.
Use ClassicLink: Establish an internal network connection between the classic-network ECS instance and the VPC-based PolarDB cluster using ClassicLink.
Use the public endpoint: Connect the ECS instance to the PolarDB cluster over the Internet using the cluster's public endpoint. This option has lower performance and security compared to VPC-based connectivity.