How do I troubleshoot snapshot restore issues from my Aurora PostgreSQL-Compatible DB cluster?

Resolution

Note: If you receive errors when you run AWS Command Line Interface (AWS CLI) commands, then see Troubleshooting errors for the AWS CLI. Also, make sure that you're using the most recent AWS CLI version.

Before you troubleshoot snapshot restore errors, verify that your snapshot is compatible with your target configuration and that you have the required permissions.

Verify snapshot compatibility before restoration

Before you restore a snapshot, verify the version compatibility to prevent errors.

Check snapshot status and engine version

You can use the console or AWS CLI to verify the version compatibility before you restore a snapshot.

To use the console, complete the following steps:

1. Open the Amazon Relational Database Service (Amazon RDS) console.
2. Choose Snapshots.
3. Select your snapshot.
4. Choose the Details tab, and then confirm the following configurations:
   Verify that the Engine parameter is aurora-postgresql.
   Confirm that the Engine version is compatible with your target version.
   Make sure that the Status is set to Available.

To use the AWS CLI to list all available Aurora PostgreSQL-Compatible versions, run the following describe-db-engine-versions command:

aws rds describe-db-engine-versions \
    --engine aurora-postgresql \
    --query "DBEngineVersions[?EngineVersion=='your-snapshot-version'].ValidUpgradeTarget[*].EngineVersion" \
    --region your-region

Note: Replace your-snapshot-version with the engine version from your snapshot and your-region with your AWS Region.

Verify IAM permissions

Make sure that your AWS Identity and Access Management (IAM) user or role has the required permissions to restore a snapshot.

To check your current permissions, run the following get-user AWS CLI command:

aws iam get-user --region your-region

Note: Replace your-region with your AWS Region.

Example IAM policy:

{
    "Version": "2012-10-17",
    "Statement": [
        {
            "Effect": "Allow",
            "Action": [
                "rds:RestoreDBClusterFromSnapshot",
                "rds:CreateDBInstance",
                "rds:DescribeDBSnapshots",
                "rds:DescribeDBClusters",
                "rds:DescribeDBInstances"
            ],
            "Resource": "*"
        }
    ]
}

Resolve IAM permission errors

If you lack the required Amazon RDS permissions, then you receive the following error message:

"User is not authorized to perform: rds:RestoreDBClusterFromSnapshot"

To resolve this error, add the required Amazon RDS permissions to your IAM policy. Complete the following steps:

1. Open the IAM console.

2. In the navigation pane, choose Users or Roles.

3. Select your user or role name.

4. Choose Add permissions.

5. Choose Create inline policy or edit a policy that is already attached to the IAM entity.

6. Choose the JSON tab.

7. Enter the policy that includes the permissions required for snapshot restoration:

   {
       "Version": "2012-10-17",
       "Statement": [
           {
               "Effect": "Allow",
               "Action": [
                   "rds:RestoreDBClusterFromSnapshot",
                   "rds:CreateDBInstance",
                   "rds:DescribeDBSnapshots",
                   "rds:DescribeDBClusterSnapshots",
                   "rds:DescribeDBClusters",
                   "rds:DescribeDBInstances"
               ],
               "Resource": "*"
           }
       ]
   }

8. Choose Next.

9. Enter a policy name. For example, enter RDSSnapshotRestorePolicy.

10. Choose Create policy.

Resolve AWS KMS encryption permission errors

If you try to restore an encrypted snapshot without proper AWS Key Management Service (AWS KMS) permissions, then you receive one of the following error messages:

"Unable to restore from encrypted snapshot"

"KMS key access denied"

To resolve the error, check the AWS KMS key that your snapshot uses, and then add the required AWS KMS permissions to your IAM policy.

To check the AWS KMS key that your snapshot uses, run the following describe-db-cluster-snapshots command:

aws rds describe-db-cluster-snapshots \
    --db-cluster-snapshot-identifier your-snapshot-id \
    --region your-region

Note: Replace your-snapshot-id with your snapshot identifier and your-region with your AWS Region.

Then, add the AWS KMS permissions to your IAM policy:

{
    "Version": "2012-10-17",
    "Statement": [
        {
            "Effect": "Allow",
            "Action": [
                "kms:Decrypt",
                "kms:CreateGrant",
                "kms:DescribeKey",
                "kms:GenerateDataKey"
            ],
            "Resource": "arn:aws:kms:region:account-id:key/key-id"
        }
    ]
}

Note: Replace region with your AWS Region, account-id with your AWS account ID, and key-id with your AWS KMS key ID.

Resolve snapshot not found errors

If you try to restore from a snapshot that doesn't exist or you can't access, then you receive the following error message:

"DBClusterSnapshotNotFoundFault: DBClusterSnapshot snapshot-id not found"

To resolve this error, verify that the snapshot exists and you have access permissions.

To list available snapshots in your account, run the following describe-db-cluster-snapshots command:

aws rds describe-db-cluster-snapshots \
    --region your-region

Note: Replace your-region with your AWS Region.

If the snapshot is shared from another AWS account, then verify that it was shared with your account and that you have accepted the share.

Resolve invalid parameter errors

If you specify an incompatible instance class during restoration, then you receive the following error message:

"InvalidParameterValue: Invalid DB Instance class"

To resolve this error, choose a compatible instance class for Aurora PostgreSQL-Compatible Edition.

To list valid instance classes for your target engine version, run the following describe-orderable-db-instance-options command:

aws rds describe-orderable-db-instance-options \
    --engine aurora-postgresql \
    --engine-version your-version \
    --region your-region

Note: Replace your-version with your PostgreSQL version, for example, 15.4. Replace your-region with your AWS Region.

Review the output and choose an instance class that supports your target engine version and required features.

Resolve subnet group errors

If you specify an invalid subnet during restoration, then you receive the following error message:

"InvalidSubnet: The requested subnet is not valid"

To resolve this error, verify that your DB subnet group has subnets in multiple Availability Zones.

To check your subnet group configuration, run the following describe-db-subnet-groups command:

aws rds describe-db-subnet-groups \
    --db-subnet-group-name your-subnet-group \
    --region your-region

Note: Replace your-subnet-group with your DB subnet group name and your-region with your AWS Region.

Verify that the subnet group contains subnets in at least two Availability Zones. If the subnet group doesn't have subnets in multiple Availability Zones, then you can modify the subnet group to add subnets in additional Availability Zones.

Resolve cross-account AWS KMS key access errors

If you try to restore an encrypted snapshot shared from another AWS account without proper AWS KMS permissions, then you receive the following error message:

"AccessDenied: Cross-account pass role is not allowed"

To resolve this error, make sure that the AWS KMS key policy allows cross-account access and your IAM role has the necessary permissions.

To check AWS KMS key policy, run the following get-key-policy command:

aws kms get-key-policy \
    --key-id your-key-id \
    --policy-name default \
    --region your-region

Note: Replace your-key-id with your AWS KMS key ID and your-region with your AWS Region.

Verify that the key policy includes a statement that grants your AWS account access to decrypt and create grants. If you can't update the AWS KMS key policy, then contact the snapshot owner to update the AWS KMS key policy.

For cross-account encrypted snapshots, you can't directly restore from the shared snapshot. Instead, use your own AWS KMS key to copy the shared snapshot to your account, then restore from the copy. For more information, see Sharing encrypted snapshots.

Resolve engine version compatibility issues

If you try to restore to an incompatible engine version, then you might receive an error during the restoration process.

To resolve, make sure that your target version is equal to or higher than the snapshot's PostgreSQL version. You can't restore to a lower version.

To check available Aurora PostgreSQL-Compatible versions, run the following describe-db-engine-versions command:

aws rds describe-db-engine-versions \
    --engine aurora-postgresql \
    --region your-region

Note: Replace your-region with your AWS Region.

Review the output to identify compatible engine versions for your restoration target.

Resolve instance class compatibility issues

If you select an instance class that doesn't support your target engine version or required features, then the restoration might fail.

To resolve this issue, choose an instance class that has the required storage and memory for your workload. Verify that the instance class supports the Aurora PostgreSQL-Compatible version that you're restoring and supports any specific features, such as Performance Insights.

To verify instance class compatibility, run the describe-orderable-db-instance-options command:

aws rds describe-orderable-db-instance-options \
    --engine aurora-postgresql \
    --engine-version your-version \
    --region your-region

Note: Replace your-version with your PostgreSQL version, for example, 15.4. Replace your-region with your AWS Region.

Related information

Restoring from a DB cluster snapshot

Sharing a DB cluster snapshot

Encrypting Amazon Aurora resources

IAM JSON policy elements: Action