Connection failures to an ApsaraDB RDS instance typically stem from one of four causes. Match your situation to the right step to diagnose faster:
| Cause | Go to |
|---|---|
| Instance is locked, restarting, or has an incorrect endpoint configured | Step 1: Check instance status and connection info |
| Your client IP address is not allowed by the whitelist | Step 2: Check whitelist configuration |
| The instance has too many connections or high resource usage | Step 3: Check instance performance |
Network commands like telnet or ping time out or fail | Step 4: Check the network and client |
| ECS instance cannot reach RDS over the internal network | ECS to RDS over internal network |
Step 1: Check instance status and connection info
Log on to the ApsaraDB RDS console. On the Instances page, check the status of your RDS instance. If the instance is locked, resolve the issue first. For details, see What do I do if my ApsaraDB RDS for MySQL instance is automatically locked due to exhausted storage capacity? A locked instance does not allow read or write operations. You can restart the instance after confirming that the restart does not affect your workloads. Proceed with caution.
In your application code or database client, verify that the connection parameters are correct — specifically, that the internal or public endpoint matches what is displayed in the console. For details, see How do I connect to an ApsaraDB RDS instance?
Step 2: Check whitelist configuration
Make sure the IP address of your client machine is added to an IP address whitelist of the RDS instance.
To quickly isolate a whitelist issue, temporarily add 0.0.0.0/0 to the whitelist. If the connection succeeds after this change, the IP address you had added earlier is incorrect. Remove 0.0.0.0/0 and add the correct IP address.
0.0.0.0/0 allows all devices to access the RDS instance. Remove this entry immediately after testing.
For instructions on configuring the whitelist, see Step 2: Connect to an ApsaraDB RDS for MySQL instance.
Common whitelist mistakes:
The default whitelist contains only
127.0.0.1, which blocks all external connections. Add your client IP address to a whitelist group.0.0.0.0is an invalid entry. The correct format is0.0.0.0/0.
Enhanced whitelist mode:
If the enhanced whitelist mode is enabled (see Change the network isolation mode of an ApsaraDB RDS instance to the enhanced whitelist mode), add IP addresses to the correct whitelist type:
| Endpoint type | IP address to add | Whitelist type |
|---|---|---|
| VPC internal endpoint | Private IP address of the ECS instance | VPC-type whitelist |
| Classic network internal endpoint | Private IP address of the ECS instance | Classic network-type whitelist |
| Public endpoint | Public IP address of the client | Classic network-type whitelist |
The VPC-type whitelist does not apply to Internet connections.
If your public IP address is not the actual egress IP:
The IP address shown by query tools or websites may differ from the actual egress IP of your machine for two reasons: public IP addresses change dynamically, and query tools sometimes return inaccurate results. See the following topics for engine-specific guidance:
Step 3: Check instance performance
Check the performance monitoring metrics of the RDS instance to determine whether resource exhaustion is causing connection failures.
Check the number of connections:
Connection exhaustion is most often caused by a large number of idle or active connections that are not being closed. To diagnose:
Find the maximum number of connections supported by your instance type in Primary ApsaraDB RDS instance types and compare it against the current connection count.
Review your application code to confirm that connections are closed after use. Connections that are not closed in time consume resources and can lead to connection exhaustion. For solutions, see What do I do if the number of connections to an ApsaraDB RDS for MySQL instance reaches the upper limit? or What do I do if excessive connections are established to an ApsaraDB RDS for PostgreSQL instance?
Upgrade the instance if resources are consistently insufficient:
If your business has grown beyond the current instance capacity, upgrade the instance configuration. During the upgrade, a transient connection lasting approximately 30 seconds may occur. Configure your application to automatically reconnect to maintain service continuity. For more information, see Limits.
Check for high network traffic or slow queries:
If network traffic usage is high, view slow query logs and optimize slow SQL statements.
For CPU utilization, memory usage, disk usage, or IOPS issues, see What do I do if the CPU utilization, memory usage, disk usage, or IOPS of an ApsaraDB RDS instance is high?
Step 4: Check the network and client
Test network connectivity:
Run ping or telnet to verify that the RDS endpoint is reachable from your machine. Replace <public endpoint> with the actual endpoint of your RDS instance:
telnet <public endpoint of the RDS instance> 3306If the connection succeeds, the command produces no output and hangs (press Ctrl+C to exit). If the connection fails, you see an error similar to:
Connecting to <public endpoint>...Could not open connection to the host, on port 3306: Connect failedIf the connection fails or times out, your local firewall may be blocking outbound traffic on port 3306. Check your firewall settings.
Rule out a client-side issue:
Try connecting with a different client to confirm whether the issue is client-specific. For connection instructions by engine, see:
ECS to RDS over internal network
If an ECS instance cannot connect to an RDS instance over the internal network, see What do I do if I fail to connect to an ApsaraDB RDS instance?
Applicable scope
ApsaraDB RDS