--- cuppy_hub: aws cuppy_path: reference/rds/errors.md cuppy_section: docs cuppy_doc: HYWR-RVVC cuppy_doc_uuid: 2c2e333b-c936-4318-ac01-5ac4ce1891d3 cuppy_permalink: https://cuppy.io/aws/d/HYWR-RVVC cuppy_version: 4 cuppy_updated: 2026-10-23T16:16:52.575Z cuppy_canonical: https://cuppy.io/aws/docs/reference/rds/errors cuppy_mcp: https://cuppy.io/mcp cuppy_body_sha256: 53a395199164e34f5c230d4e6075d0608fabe08316e496cef0b9f2ccc0c030e2 # cuppy_body_sha256 is over the document body ALONE, excluding both generated blocks. --- # Amazon RDS and Aurora errors and bad states **Most RDS failures show up as an instance status, not an error message.** Check it first: ``` aws rds describe-db-instances --db-instance-identifier --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 --query DBInstances[0].VpcSecurityGroups`, then `aws ec2 describe-security-group-rules --filters Name=group-id,Values=` | | 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 --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 ` from another network | | Status `creating` | Wait for `available` (can take up to 20 minutes) | `aws rds describe-db-instances --db-instance-identifier --query 'DBInstances[0].DBInstanceStatus'` | | Testing with ping | RDS doesn't answer ICMP: use `nc -zv ` | `nc -zv ` | | 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 --allocated-storage --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 --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 ` (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 --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:::dbuser:/`. 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 --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 ` 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

` → `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

` → `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

` → `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 --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. --- You are reading one file. The same content is free over MCP at https://cuppy.io/mcp with no signup: ranked search across all 131 documents in this hub, the merged view when you work in a layer, known workarounds matched to the error you hit, and depth control so you spend tokens on what you need. Start with the `_hello` tool. How to connect: https://cuppy.io/aws/ Something wrong in this document? Report it with the `session feedback` tool on the same endpoint.