How do I resolve issues with an Amazon DocumentDB instance that's in an incompatible-network state?

Short Description

An incompatible-network state occurs because of one or more of the following issues with the Amazon DocumentDB instance:

• There are no available IP addresses in the subnet that the Amazon DocumentDB instance was launched in.
• The subnet listed in the Amazon DocumentDB DB subnet group doesn't exist in the Amazon Virtual Private Cloud (Amazon VPC).
• You reached your service quota for elastic network interfaces in the AWS Region that you're using.

If you have one of these issues, then your Amazon DocumentDB instance might enter the incompatible-network state when you perform one of the following actions:

• Modify the Amazon DocumentDB instance's class.
• Add a new Amazon DocumentDB instance to the cluster.
• Replace a host because of a maintenance event.
• Create a new Amazon DocumentDB instance after the elastic network interfaces reach their quota.
• Restore from an Amazon DocumentDB snapshot backup.
• Start an Amazon DocumentDB cluster that was stopped.

Resolution

The incompatible-network state means that the Amazon DocumentDB instance might still be accessible at the database level, but you can't modify or reboot the instance. It's a best practice to always have a backup so that you can restore the data to another instance if your instance enters an incompatible-network state.

To troubleshoot issues with an Amazon DocumentDB instance in an incompatible-network state, choose one of the following solutions:

• Use the AWSSupport-ValidateRdsNetworkConfiguration runbook.
• Use the AWS Management Console.

Use the AWSSupport-ValidateRdsNetworkConfiguration runbook

To identify why your Amazon DocumentDB instance is in an incompatible-network state, use the AWSSupport-ValidateRdsNetworkConfiguration runbook. To avoid the incompatible-network state, use this runbook when you perform any modifications or start a stopped instance.

Note: Before you begin the AWSSupport-ValidateRdsNetworkConfiguration runbook, make sure that your AWS Identity and Access Management (IAM) user or role has the required permissions. For more information, see the Required IAM permissions section of AWSSupport-ValidateRdsNetworkConfiguration.

To troubleshoot from the AWSSupport-ValidateRdsNetworkConfiguration runbook, complete the following steps:

1. Sign in to the AWS Systems Manager console and access the AWSSupport-ValidateRdsNetworkConfiguration runbook.
2. Choose Execute automation.
3. Enter the following values:
   For AutomationAssumeRole, enter the ARN of the IAM role that allows automation to perform actions on your behalf. If a role isn't specified, then Automation uses the permissions of the user who starts the runbook.
   For DBInstanceIdentifier, enter the Instance Identifier for your Amazon DocumentDB instance.
4. Choose Execute.
5. After the automation completes, review the detailed results in the Outputs section. The parameter generateReport.Report shows a consolidated report of all the checks that are performed as part of this runbook.
6. (Optional) Check the ### [Next Steps] section of the output report for further troubleshooting steps.

Use the AWS Management Console

To troubleshoot from the AWS Management Console, complete the following steps:

1. Open the Amazon DocumentDB console, and then choose Instances from the navigation pane.
2. Choose the Amazon DocumentDB instance that's in an incompatible-network state. Then, note the VPC ID from the instance details.
3. Open the Amazon VPC console, and then choose Subnets from the navigation pane. Verify that all the subnet groups in the VPC used by the Amazon DocumentDB cluster exist and are in an available state.
4. Confirm that all subnets in the subnet group used by the Amazon DocumentDB cluster have available IP addresses.
5. Open the Amazon Elastic Compute Cloud (Amazon EC2) console, and then confirm that you haven't reached the quota for elastic network interfaces. If you've reached the quota, then request a service quota increase. For more information, see Network interfaces.

If the Amazon DocumentDB instance is already in an incompatible-network state, then choose one of the following methods for your Amazon DocumentDB cluster:

• Create a new Amazon DocumentDB instance in the cluster after you resolve the issue that caused the incompatible-network state. After you have a cluster that's running with a new active Amazon DocumentDB instance, delete the instance that was in an incompatible-network state.
  Important: Don't delete the entire cluster. Instead, delete only the incompatible-network state instance. Also, make sure that the new active Amazon DocumentDB instance is in the same cluster as the old incompatible-network state instance.
• Temporarily stop any writes to the Amazon DocumentDB instance, and then perform a point-in-time recovery (PITR) to create a new cluster.

Related Information

Monitoring an Amazon DocumentDB instance's status