How do I troubleshoot the errors that I get when I create or update RDS DB resources in CloudFormation?

Short description

You might see an error when you create or update a CloudFormation stack for an Amazon RDS resource. These resources might include the DB instance, the DB cluster, or the DB parameter group. The error occurs when the Amazon RDS resource isn't supported for updates. Or you specified non-valid properties for the Amazon RDS resource.

Resolution

Error: "Cannot upgrade aurora-postgresql (or any RDS version) from 13.## to 14.## (Service: Rds, Status Code: 400)"

This error might occur when you do a minor or major version upgrade to the RDS DB engine.
RDS performs prechecks to confirm feasibility before an engine version upgrade. The error occurs when there's a failure during precheck.

Use the following links for the AWS supported version upgrade for your type of Amazon RDS:

• Amazon Aurora PostgreSQL-Compatible Edition: How to perform a major version upgrade
• Amazon Aurora MySQL-Compatible Edition: Database engine updates for Amazon Aurora MySQL
• Amazon RDS for Oracle: Upgrading the RDS for Oracle DB engine
• Amazon RDS for MySQL: Upgrading the MySQL DB engine
• Amazon RDS for PostgreSQL: Upgrading the PostgreSQL DB engine for Amazon RDS
• Amazon RDS for MariaDB: Upgrading the MariaDB DB engine

Error: "The current DB instance parameter group is custom. You must explicitly specify a new DB instance parameter group, either default or custom, for the engine version upgrade."

You might see this error when you use AWS CloudFormation to perform a major version upgrade of the RDS DB Database instance. The resource handler returns this error message when any of the following conditions are true:

• The parameter group version that's used for the engine version upgrade isn't valid. You must use the supported default parameter group version for the upgrade.
• The custom parameter group resource definition is directly updated in the stack template. For more information, see AWS::RDS::Cluster unable to upgrade major Engine Version with a Custom Parameter Group directly on the GitHub website.

To resolve this error, complete the following steps:

1. Update the DB instance resource definition in the stack template to use the current engine version's supported default DB parameter group. Update the stack with the modified template.
2. Update the DB instance resource definition to use the upgraded engine version and the version's supported default DB parameter group.
3. Update your DB instance resource definition to use the required custom DB parameter group with the upgraded engine version.

Error caused by a drift in CloudFormation during manual upgrade

You might see this error when an RDS DB instance or cluster version is upgraded manually (that is, when you perform an out-of-band upgrade). When a CloudFormation created resource is modified manually, CloudFormation doesn't track the changes that were made to the resources. This results in a drift on the stack.

To make sure that the actual resource is in sync with the CloudFormation stack, complete the following steps:

1. Modify the stack template associated with the drifted stack. Include a DeletionPolicy attribute in the cluster resource with a value of Retain on the RDS DB instance or cluster. Then, update the stack with the modified template. This retains the actual resource while you delete the resource from the stack.
2. Remove the drifted resource from the stack template, and then update the stack.
3. Import the resource back into the stack.
   Note: To avoid drift, confirm that the stack template that you use to import the RDS resource reflects the current configuration of the RDS DB resource.
4. Perform a drift detection operation on the stack to verify that the drift is resolved.

Error: "Cannot change master user password while doing a major version upgrade. (Service: Rds, Status Code)"

You receive this error when the RDS DB password was changed.

Note: You can't perform a password rotation along with a major version upgrade.

To resolve this error, complete the following steps:

1. Perform a stack update with the existing template. This update uses the rotated password along with the current engine version. When the stack update is complete, the database credentials are reset with the new password.
2. Perform a stack update to upgrade to the target major engine version.

Error: "DB Instance already exists" or a naming conflict when you update EngineVersion with other properties

When you update EngineVersion on an AWS::RDS::DBInstance resource that has a hardcoded DBInstanceIdentifier, you might receive a naming conflict error.
EngineVersion alone is an in-place update. But if the same update also changes a property that requires replacement, such as DBSubnetGroupName, KmsKeyId, or DBClusterIdentifier, then CloudFormation replaces the instance instead. During replacement, CloudFormation creates the new instance before it deletes the old one, so the hardcoded identifier causes a naming conflict.

Note: When you specify a DBInstanceIdentifier, you can't perform updates that require replacement unless you also assign a new name.

To resolve the error, take one of the following actions:

• Change only EngineVersion in one update, and apply the replacement-triggering property separately.
• Specify a new DBInstanceIdentifier in the same update to avoid the naming conflict.
• Remove the hardcoded DBInstanceIdentifier so CloudFormation generates a unique name.

To find the triggering property, check the Update requires value for each changed property in the AWS::RDS::DBInstance reference. Any property labeled Replacement replaces the instance.

Important: Replacement deletes the original instance. Take a snapshot before you run a stack update that replaces the instance.

Related information

describe-engine-default-parameters