AWSMid

Can't connect to an RDS database

RDS connection failures are usually the security group, public accessibility, the subnet route or the instance state. Test with nc before blaming the client.

What you see

  • Connection times out to the RDS endpoint
  • Could not open connection to the host, on port ...: Connect failed

What it means

By default, DB instances do not allow access. Access is granted through a security group on the VPC. If the path between client and database is missing a rule, a route or a public address, the connection just times out.

A timeout means the network path is wrong. An authentication error means you did connect, and the problem is the username or password.

How to confirm the cause

  1. 1
    Check the instance is available
    aws rds describe-db-instances --db-instance-identifier DB_ID --query 'DBInstances[0].[DBInstanceStatus,PubliclyAccessible,Endpoint.Address,Endpoint.Port]'

    A new instance stays creating until ready, which can take up to 20 minutes.

  2. 2
    Test the TCP path from the client
    nc -zv DB_ENDPOINT PORT

    Example from the official docs

    Connection to ... port [tcp/...] succeeded!

    If it succeeds, the security group is fine. RDS does not accept ping, so do not test with ICMP.

  3. 3
    Read the security group's inbound rules
    aws ec2 describe-security-groups --group-ids SG_ID

    Look for a rule that allows the database port from your client's address or security group.

Causes and fixes

  • Security group has no inbound rule

    HOW TO TELL
    nc times out. No rule allows your client on the DB port.
    ROOT CAUSE
    No inbound rule allows the traffic, so the security group drops it.
    FIX
    Add an inbound rule for the database port from the client's security group or address range. Client addresses in 169.254.0.0/16 are not permitted.
  • Instance is not publicly accessible

    HOW TO TELL
    You connect from outside the VPC and PubliclyAccessible is false.
    ROOT CAUSE
    Without a public address, the instance cannot be reached from the internet.
    FIX
    Connect from inside the VPC, or modify the instance to be publicly accessible, which also needs an internet gateway on the subnets.
  • Subnet has no route to an internet gateway

    HOW TO TELL
    The instance is public but the subnet's route table has no 0.0.0.0/0 route to an internet gateway.
    ROOT CAUSE
    Traffic has no way out of the VPC.
    FIX
    Attach an internet gateway to the VPC and add the route to the subnet's route table.
  • Local firewall blocks the port

    HOW TO TELL
    nc fails only from your office or home network.
    ROOT CAUSE
    Your own network does not allow outbound traffic on the database port.
    FIX
    Ask your network administrator to allow it.

How to stop it coming back

  • Keep databases private and reach them through a bastion, VPN or app tier.
  • Reference security groups, not IP addresses, in rules.
  • Monitor DatabaseConnections and connection errors.

Keep going

Sources

AWS documentation (docs.aws.amazon.com), read 18 Nov 2026.

Search

Search cheat sheets and projects