How do I troubleshoot connection timed out errors when I try to connect to my Aurora PostgreSQL-Compatible database cluster?

Resolution

Note: If you receive errors when you run AWS Command Line Interface (AWS CLI) commands, then see Troubleshooting errors for the AWS CLI. Also, make sure that you're using the most recent AWS CLI version.

Network configuration issues often cause connection timed out errors when you connect to an Aurora PostgreSQL-Compatible DB cluster. To identify and resolve connection timed out issues, take the following actions.

Check the database instance status

Complete the following steps:

1. Open the Amazon Relational Database Service (Amazon RDS) console.
2. In the navigation pane, choose Databases.
3. In the Status column, make sure that your Aurora PostgreSQL-Compatible DB instance is in the Available state.
   Important: If the instance isn't available, then wait for it to become available before you proceed with further troubleshooting.

Check the security group configurations

To check both inbound and outbound rules, complete the following steps:

1. Open the Amazon Elastic Compute Cloud (Amazon EC2) console.
2. In the navigation pane, choose Security Groups.
3. Select the security group that's associated with your Aurora PostgreSQL-Compatible DB cluster.
4. Choose Inbound rules.
5. Make sure that there's a rule that permits traffic from your client's IP address or security group on port 5432 or your custom port.
   Note: Choose Edit inbound rules to add or modify rules that accepts the required traffic.
6. If you connect from an Amazon EC2 instance, then choose Outbound rules.
7. Make sure that the security group of the Amazon EC2 instance lets outbound traffic to the Aurora PostgreSQL-Compatible cluster's security group on port 5432.
   Note: Choose Edit outbound rules to add or modify rules that accepts the required traffic.

Check the network ACL configurations

To check the network access control list (network ACL) configurations, complete the following steps:

1. Open the Amazon Virtual Private Cloud (Amazon VPC) console.
2. In the navigation pane, choose Network ACLs.
3. Select the network ACL that's associated with the subnet of your Aurora PostgreSQL-Compatible DB cluster.
4. Choose both Inbound rules and Outbound rules, and then verify that the rules let traffic on port 5432 between your client and the database.

Check the route table configuration

To check the route table configuration, complete the following steps:

1. Open the Amazon VPC console.
2. In the navigation pane, choose Route Tables.
3. Select the route table that's associated with your Aurora PostgreSQL-Compatible DB cluster's subnet.
4. Verify that there's a route for your classless inter-domain routing that points to the correct target.

For example, the target can be the Internet Gateway, NAT Gateway, or peering connection. If you connect from a different VPC or an on-premises network, then make sure that the necessary routes are in place.

Check VPC peering or transit gateway configurations

If you connect from different VPCs through VPC peering, then complete the following steps:

1. Follow the VPC peering process to verify that VPC peering is correctly set up between VPCs.
2. Check that the route tables in both VPCs have the necessary routes to direct traffic between them.
3. Verify that the security groups in both VPCs accepts the required traffic.

If you connect from different VPCs through transit gateway, then complete the following steps:

1. Follow the design best practices to make sure that the transit gateway is correctly set up between VPCs.
2. Check that the route tables for all VPC attachments have the necessary routes to direct traffic between them.
3. Verify that the security groups in both VPCs accepts the required traffic.

Check the DNS resolution

If you connect across VPCs, then check that you activated DNS resolution for your VPC peering connection.

Complete the following steps:

1. Open the Amazon VPC console.
2. In the navigation pane, choose Peering connections.
3. Select your peering connection.
4. Choose Actions, and then Edit DNS settings.
5. In the Edit DNS settings section, permit DNS resolution for both the requester and accepter VPCs.

Check the internet gateway IP address

If you try to connect from outside the VPC and the cluster is publicly accessible, then complete the following steps:

1. Open the Amazon VPC console.
2. In the navigation pane, choose Internet gateways.
3. Locate the internet gateway for your VPC, and then verify that the internet gateway is in the Attached state.
4. Select the VPC ID for your internet gateway.
5. In Details, select the Main route table.
6. Select Routes, and then verify that there's a route with destination 0.0.0.0/0 IP address that points to the target internet gateway.

Test connection to the database instance

Test your connection to verify if you have a network-related or authentication-related issue. If the connection test succeeds, then the issue is likely with your database credentials.

To test network connectivity with telnet, run the following command:

telnet CLUSTER-ENDPOINT 5432

Note: Replace CLUSTER-ENDPOINT with your Aurora PostgreSQL-Compatible cluster endpoint and 5432 with your database port. The default database port is 5432 for PostgreSQL.

To test network connectivity when telnet isn't available, run the following command:

nc -zv CLUSTER-ENDPOINT 5432

Note: Replace CLUSTER-ENDPOINT with your Aurora PostgreSQL-Compatible cluster endpoint and 5432 with your database port.

If the connection succeeds, your security group is properly configured.

Note: Amazon RDS doesn't accept Internet Control Message Protocol (ICMP) traffic, including ping.

Check the Publicly Accessible configuration

If you try to connect to your cluster from outside the VPC, then your cluster must be publicly accessible. Or, you can use other connection methods such as a bastion host or AWS Direct Connect.

To check if your cluster is publicly accessible, complete the following steps:

1. Open the Amazon RDS console.
2. In the navigation pane, choose Databases.
3. Select your Aurora PostgreSQL-Compatible cluster, and then choose Modify.
4. In the Connectivity section, choose Additional configuration.
5. Verify that you set the cluster to Publicly accessible.

Check for IP address conflicts

Verify that there are no IP address conflicts between your local network and the VPC CIDR range. If conflicts exist, then you might need to use NAT or adjust your network configuration.

To check the CIDR for your VPC, complete the following steps:

1. Open the Amazon VPC console.
2. In the navigation pane, choose Your VPCs, and then select the VPC that you use for your local network connection.
3. Choose the CIDRs tab, and then make sure that the CIDR block doesn't overlap with any IP address on your local network.

Check VPC CIDR using AWS CLI

To use the AWS CLI to describe VPC CIDR blocks, run the following describe-vpcs AWS CLI command:

aws ec2 describe-vpcs \
    --vpc-ids VPC-ID \
    --region REGION

Note: Replace VPC-ID with your VPC ID and REGION with your AWS Region.

Related information

Connecting to an Amazon Aurora DB cluster

Control traffic to your AWS resources using security groups

Control subnet traffic with network access control lists

Manage subnet route tables

What is VPC peering?