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 any of the following are true:

• The Amazon RDS resource isn't supported for updates.
• You specified non-valid properties for the Amazon RDS resource.

Resolution

These are the common errors that might occur during Amazon RDS DB resource updates:

Error: "Cannot upgrade aurora-postgresql (or any RDS version) from 13.XX to 14.YY (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 to make sure that you are using 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.

Follow all the steps below to resolve the error:

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.

Use the following steps to make sure that the actual resource is in sync with the CloudFormation stack:

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)"

This error indicates that the RDS DB password was changed.
Note: You can't perform a password rotation along with a major version upgrade.

Follow these steps to resolve the error:

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.

Related information

describe-engine-default-parameters