Amazon RDS and Aurora errors and bad states
Look up an RDS or Aurora problem by symptom, status or message — cannot connect, storage-full, incompatible-parameters, incompatible-network, IAM authentication failures, connection limits and RDS Proxy pitfalls — with cause and fix for each.
markdownreferencev4HYWR-RVVCstage: operatetrust: officialservice: rdsinterface: anyRDS cannot connectstorage-fullincompatible-parametersincompatible-networkfailed to retrieve account attributestoo many connectionsmax_connectionsPAM authentication failedAccess denied for user IAMrds-db:connect deniedRDS Proxy rdsproxyadminFreeStorageSpacecreating status
Most RDS failures show up as an instance status, not an error message. Check it first:
aws rds describe-db-instances --db-instance-identifier <id> --query 'DBInstances[0].DBInstanceStatus'Then read Logs & events → Recent events in the console.
Can't connect
| Condition | Fix | Check |
|---|---|---|
| Security group has no inbound rule for the client on the engine port | Add one (from the app's security group, or your IP) | aws rds describe-db-instances --db-instance-identifier <id> --query DBInstances[0].VpcSecurityGroups, then aws ec2 describe-security-group-rules --filters Name=group-id,Values=<sg> |
| Client outside the VPC, instance not publicly accessible | Modify Public accessibility = Yes, and the subnets need a 0.0.0.0/0 route to an internet gateway. Or connect from inside the VPC | aws rds describe-db-instances --db-instance-identifier <id> --query 'DBInstances[0].[PubliclyAccessible,DBSubnetGroup.Subnets[].SubnetIdentifier]', then each subnet's route table |
Client address in 169.254.0.0/16 | Not permitted | The client's own address (ip addr) |
| Local or corporate firewall blocks the port | Open it, or use another network | nc -zv <endpoint> <port> from another network |
Status creating | Wait for available (can take up to 20 minutes) | aws rds describe-db-instances --db-instance-identifier <id> --query 'DBInstances[0].DBInstanceStatus' |
| Testing with ping | RDS doesn't answer ICMP: use nc -zv <endpoint> <port> | nc -zv <endpoint> <port> |
| Lambda or Fargate in the VPC times out | Security group chaining or subnets (patterns/lambda-to-rds.md) | nc -zv from the same subnet and security group (patterns/lambda-to-rds.md) |
Bad states
| Status | Cause → fix | Check |
|---|---|---|
storage-full | Out of storage. aws rds modify-db-instance --db-instance-identifier <id> --allocated-storage <GiB> --apply-immediately, then watch it go modifying → available. Alarm on FreeStorageSpace | The FreeStorageSpace metric |
incompatible-parameters | Memory settings too large: the instance restarted 3+ times in an hour or 5+ in a day, and estimated memory use exceeds 1.2× the class memory. Lower innodb_buffer_pool_size or max_connections in the parameter group, then reboot | aws rds describe-events --source-identifier <id> --source-type db-instance --duration 1440 |
incompatible-network | After a class change, Multi-AZ conversion, host replacement, snapshot restore or start-after-stop, the network couldn't be set up. Run aws rds start-db-instance --db-instance-identifier <id> (may cause downtime; doesn't fix SQL Server). Then read the events for DNS, ENI, GATEWAY, IP, SECURITY GROUP, SUBNET or VPC messages. Last resort: point-in-time restore to a new instance | Same call; the subnet group's free IPs (aws ec2 describe-subnets → AvailableIpAddressCount) |
Console: failed to retrieve account attributes, certain console functions may be impaired. | Missing IAM permissions, or the account isn't fully set up | aws iam simulate-principal-policy --policy-source-arn <caller> --action-names rds:DescribeAccountAttributes |
Connection limits
max_connections defaults from the instance class memory, and the parameter group can set it. Too many short-lived connections (typical of Lambda) exhaust it. Pool in the application, or put RDS Proxy in front. Raising max_connections too far can push the instance into incompatible-parameters. The exact "too many connections" message differs by engine (UNVERIFIED wording; not on the troubleshooting page).
IAM database authentication failures
| Symptom | Cause → fix | Check |
|---|---|---|
Authentication fails with a token (PostgreSQL commonly reports PAM authentication failed, MySQL Access denied for user; both UNVERIFIED strings) | Token older than 15 minutes; token generated for a custom DNS name instead of the RDS endpoint; driver truncated the ~1 KB token; temporary credentials expired before connecting; DB user lacks rds_iam (PostgreSQL); IAM auth not enabled on the instance | The token's age and the host it was generated for; the database's log for the auth failure |
| Caller denied | Missing rds-db:connect on arn:aws:rds-db:<region>:<account>:dbuser:<DbiResourceId>/<user>. Aurora needs the cluster resource ID; through RDS Proxy, the proxy ID. Conditions on aws:SourceIp/SourceVpc/SourceVpce aren't supported, so a policy relying on them never allows | aws rds describe-db-instances --db-instance-identifier <id> --query DBInstances[0].DbiResourceId (or describe-db-clusters → DbClusterResourceId) vs the policy's resource ARN |
| Password login stopped working on PostgreSQL | The user was granted rds_iam, so IAM auth now takes precedence | PostgreSQL: \du <user> shows membership of rds_iam |
| No trace in CloudTrail | Expected: IAM DB auth and token generation aren't logged | None needed |
RDS Proxy
| Symptom | Cause → fix | Check |
|---|---|---|
| Proxy completely unavailable | The rdsproxyadmin database user was modified or deleted | aws rds describe-db-proxy-targets --db-proxy-name <p> → TargetHealth.Reason, Description |
| PostgreSQL proxy down for up to 60 s | Authentication was switched to SCRAM-only | aws rds describe-db-proxies --db-proxy-name <p> → Auth |
| Parameter change not taking effect through the proxy | It needs a database reboot | describe-db-instances → DBParameterGroups[].ParameterApplyStatus (pending-reboot) |
| Pooling ineffective, connection count high | Session pinning (statements over 16 KB, session-state changes) | The proxy's DatabaseConnectionsCurrentlySessionPinned metric |
| Can't create a proxy | It must be in the database's VPC. Not supported with dedicated tenancy or Encryption Controls in enforce mode | The proxy's VPC vs describe-db-instances → DBSubnetGroup.VpcId |
| Clients rejected under load | Beyond the proxy's connection limits it queues, throttles, then rejects. Raise the limits or the instance size | aws rds describe-db-proxy-target-groups --db-proxy-name <p> → ConnectionPoolConfig |
Restores and snapshots
A point-in-time restore or snapshot restore always creates a new instance, with the default parameter group, option group and security group unless you specify yours. "Missing settings" after a restore are usually these. See reference/rds/backups-and-restore.md.
When none of these fits
Read the instance's events (aws rds describe-events --source-type db-instance --source-identifier <id> --duration 1440) and its status (describe-db-instances). Then the engine's own error log (aws rds describe-db-log-files / download-db-log-file-portion). Connection problems follow guides/rds/connect-securely.md. Keep the event messages and times for AWS Support.