How do I troubleshoot an RDS DB instance class that I can't view or change?

Short description

The following issues most commonly result in an RDS DB instance class that you can't view or modify:

• The DB engine version is either deprecated or on track for deprecation.
• The target version of the database engine doesn't support the instance class.
• A specific Availability Zone doesn't have the capacity or availability for the instance class.

To troubleshoot your DB instance, refer to the resolution that applies to your issue.

Resolution

If you receive errors when running AWS Command Line Interface (AWS CLI) commands, make sure that you're using the most recent version of the AWS CLI.

The DB engine version is either deprecated or on track for deprecation

If the DB engine version is either deprecated or soon to be deprecated, then you can't select a DB instance class. In this case, the Amazon RDS console doesn't display any instance class options. This typically occurs when you try to restore a snapshot from a deprecated DB engine version to the next available version.

To resolve this issue, use the following AWS CLI commands to restore an Amazon RDS snapshot or restore an Amazon Aurora cluster snapshot.

For an RDS instance

Run the restore-db-instance-from-db-snapshot AWS CLI command:

aws rds restore-db-instance-from-db-snapshot \  
    --db-instance-identifier INSTANCE_NAME \  
    --db-snapshot-identifier SNAPSHOT_NAME \  
        --db-instance-class INSTANCE_CLASS 

Note: Replace INSTANCE_NAME, SNAPSHOT_NAME, and INSTANCE_CLASS with your values.

For example, the following command restores a db.m5.large instance class cluster:

aws rds restore-db-instance-from-db-snapshot \  
    --db-instance-identifier testcli-instance \  
    --db-snapshot-identifier my-snapshot \  
    --db-instance-class db.m5.large

For an Amazon Aurora cluster

Run the restore-db-cluster-from-snapshot AWS CLI command:

aws rds restore-db-cluster-from-snapshot \  
    --db-cluster-identifier CLUSTER_NAME \  
    --snapshot-identifier SNAPSHOT_NAME \  
    --engine AURORA_ENGINE \  
    --engine-version AURORA_VERSION \  
    --db-cluster-parameter-group-name PARAMETER_GROUP_NAME

Note: Replace CLUSTER_NAME, SNAPSHOT_NAME, AURORA_ENGINE, AURORA_VERSION, and PARAMETER_GROUP_NAME with your values.

For example, the following command restores an Aurora MySQL-Compatible Edition version 3.02.2 cluster:

aws rds restore-db-cluster-from-snapshot \  
    --db-cluster-identifier mynewcluster \  
    --snapshot-identifier aurora-test \  
    --engine aurora-mysql \  
    --engine-version 8.0.mysql_aurora.3.02.2 \  
    --db-cluster-parameter-group-name auroramysql8

When you use the AWS CLI to restore the cluster, it doesn't create DB instances. To create the DB instance for the cluster, run the create-db-instance AWS CLI command or use the CreateDBInstance API.

create-db-instance:

aws rds create-db-instance \  
 --db-cluster-identifier CLUSTER_NAME \  
 --db-instance-identifier INSTANCE_NAME \  
 --db-instance-class INSTANCE_CLASS \  
 --engine AURORA_ENGINE 

Note: Replace CLUSTER_NAME, INSTANCE_NAME, INSTANCE_CLASS, and AURORA_ENGINE with your values.

If you want to scale your instance class for a deprecated Amazon RDS or Aurora engine version, then the instance class options aren't visible in Amazon RDS console. In this case, run the modify-db-instance AWS CLI command to modify the RDS or Aurora instance.

modify-db-instance:

aws rds modify-db-instance \  
    --db-instance-identifier INSTANCE_NAME \  
    --db-instance-class INSTANCE_CLASS \  
    --apply-immediately

Note: Replace INSTANCE_NAME and INSTANCE_CLASS with your values.

The target version of the database engine doesn't support the instance class

Not all DB engine versions support all instance classes. For a list of supported RDS DB engines, see Supported DB engines for DB instance classes. For a list of supported Aurora DB engines, see Supported Aurora DB engines for DB instance classes.

To resolve your issue, select a supported instance class for the corresponding DB engine version.

Use the AWS CLI to find your supported instance options

To list the instance class options for a specific DB engine version, run the describe-orderable-db-instance-options AWS CLI command:

aws rds describe-orderable-db-instance-options \  
    --engine ENGINE_NAME \  
    --engine-version ENGINE_VERSION \  
    --query "*[].{DBInstanceClass:DBInstanceClass,StorageType:StorageType}|[?StorageType=='gp2']|[].{DBInstanceClass:DBInstanceClass}" \  
    --region REGION \  
    --output text

Note: Replace ENGINE_NAME, ENGINE_VERSION, and REGION with your values.

For example, the following command lists the supported instance classes for an Amazon RDS for PostgreSQL DB engine version 13.6 in the us-east-1 AWS Region:

aws rds describe-orderable-db-instance-options \  
    --engine postgres \  
    --engine-version 13.6 \  
    --query "*[].{DBInstanceClass:DBInstanceClass,StorageType:StorageType}|[?StorageType=='gp2']|[].{DBInstanceClass:DBInstanceClass}" \  
    --region us-east-1 \  
    --output text

To list the DB engine versions that support a specific DB instance class, run the describe-orderable-db-instance-options AWS CLI command:

aws rds describe-orderable-db-instance-options \  
 --engine ENGINE_NAME \  
 --db-instance-class INSTANCE_CLASS \  
 --query "*[].{EngineVersion:EngineVersion,StorageType:StorageType}|[?StorageType=='gp2']|[].{EngineVersion:EngineVersion}" \  
 --region REGION \  
 --output text 

Note: Replace ENGINE_NAME, INSTANCE_CLASS, and REGION with your values.

For example, the following command lists the Amazon RDS for PostgreSQL DB engine versions that support the db.r5.large instance class in us-east-1:

aws rds describe-orderable-db-instance-options \  
 --engine postgres \  
 --db-instance-class db.r5.large \  
 --query "*[].{EngineVersion:EngineVersion,StorageType:StorageType}|[?StorageType=='gp2']|[].{EngineVersion:EngineVersion}" \  
 --region us-east-1 \  
 --output text

A specific Availability Zone doesn't have the capacity or availability for the instance class

An instance class might not be available in a specific Availability Zone. This is typically because of insufficient hardware capacity in the Availability Zone. In this case, you might see an error similar to the following one:

"Cannot modify the instance class because there are no instances of the requested class available in the current instance's availability zone.
Please try your request again at a later time."

To confirm if an Availability Zone supports an instance class and DB engine version, run the describe-orderable-db-instance-options AWS CLI command. The following example lists the Availability Zones in us-east-1 that support the Amazon RDS for MySQL DB engine version 8.0.32 with the db.m6i.xlarge instance class:

aws rds describe-orderable-db-instance-options \  
    --engine mysql \  
    --engine-version 8.0.32 --db-instance-class db.m6i.xlarge \  
    --region us-east-1   
    --query "OrderableDBInstanceOptions[].AvailabilityZones"

You can also get information about orderable options, including Availability Zones for DB instances. The following example lists information for an RDS for MySQL DB engine and db.t2.micro instance class in the us-east-1 Region:

aws rds describe-orderable-db-instance-options \  
 --engine mysql \  
 --db-instance-class db.t2.micro \  
 --region us-east-1

To list all available instance classes in a specific Availability Zone, run the describe-instance-type-offerings AWS CLI command. The following example lists instance classes for the us-east-1 Region:

aws ec2 describe-instance-type-offerings \  
    --location-type availability-zone \  
    --filters Name=location,Values=us-east-1a

Note: This command and its output are specific to Amazon Elastic Compute Cloud (Amazon EC2) availability. Therefore, Amazon RDS or Aurora might not support some instance classes from this output.

Troubleshoot Availability Zones

When an instance isn't available in a specific Availability Zone, you can take one of the following actions:

• Check at a later date to see if the instance class became available.
• Choose another available DB instance class that meets your needs. Then, scale the instance to your intended instance class when it becomes available.
• Restore the DB instance from a snapshot with your desired instance class in a different Availability Zone.
• Modify the instance class. Complete the following steps to modify an RDS instance or Aurora instance.

Modify an RDS instance:

1. Turn on the Multi-AZ option.
2. Reboot the instance with failover.
3. Change the class for the new primary instance.
   Note: After a failover, your new primary instance is in a different Availability Zone.
4. Turn off the Multi-AZ option.

Modify an Aurora instance:

1. Create a reader instance in another Availability Zone.
2. Modify the instance class of the reader instance.
3. Perform a failover to confirm that the reader instance is the new primary instance.
4. Delete the old primary instance.
   Note: After the failover, it becomes a reader instance.

Troubleshoot an “InsufficientDBInstanceCapacity” error

When you create, start, or modify a DB instance, you might receive an InsufficientDBInstanceCapacity error. This indicates that the requested Availability Zone doesn't support the requested DB instance class. Try the following steps to resolve this issue:

• Retry the request with a different DB instance class.
• Retry the request with a different Availability Zone.
• Retry the request without specifying an Availability Zone.