Why can't I connect to my Amazon DocumentDB cluster?

Short description

Amazon DocumentDB is a virtual private cloud (VPC) only service and doesn't support the use of public endpoints. To connect, you must use an Amazon Elastic Compute Cloud (Amazon EC2) instance or another AWS service in the same VPC as your instance.

To access Amazon DocumentDB from EC2 instances or other AWS services in different VPCs or AWS Regions, use Amazon Virtual Private Cloud (Amazon VPC) peering or AWS Transit Gateway. If you must access your Amazon DocumentDB cluster from outside the AWS network, then use SSH tunneling or AWS Client VPN.

Use the following troubleshooting steps to resolve connection issues.

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.

The DB instance isn't in the Available state

Check that your cluster has at least one instance. Your instances and cluster must be in the Available state to accept connections.

The source doesn't have access to the cluster

Confirm that the source that you use to connect to the Amazon DocumentDB instance has access to the cluster in the following locations:

• Network access control lists (ACLs)
• Local firewalls
• Security group rules

Take the following actions so that traffic isn't blocked from the source that connects to your DB instance:

• If necessary, configure security group rules to allows source traffic in and out of the DB instance. You can specify an IP address, a range of IP addresses, or another VPC security group.
• If you use network ACLs in your VPC, then add rules to allow inbound and outbound traffic to and from the DB instance. For more information, see Network ACL rules.
• Configure your network to allow traffic to and from the ports that the DB instance uses for inbound and outbound communication.

Note: When you use SSH tunneling to connect to the Amazon DocumentDB cluster outside your VPC, check the EC2 instance that you use as a bastion host. Make sure that it has the required network configurations to allow traffic to and from the cluster.

The Amazon VPC subnet route tables don't allow traffic

The route tables that are associated with your cluster's subnets must have a valid route to your source. Also, the route tables that are associated with your source's subnets must have a valid route to your cluster.

If your source and cluster belong to the same VPC, then configure a local route in the route table of the subnets. If you use VPC peering to connect, then make sure that both VPC route tables have a route to the peered VPC or subnet CIDR block. For more information, see Example routing options.

Your primary DB instance might fail over to a standby replica. If the replica uses a different route table, then the traffic might not route correctly. To avoid this issue, make sure that your cluster subnets and source subnets use the correct route tables.

The DNS name or endpoint is incorrect

Confirm that you use the correct DNS name or endpoint to connect to the cluster. Then, confirm that the endpoint is in the correct format for the client that you use to connect to the DB instance.

To troubleshoot DNS and connectivity issues, see Can't connect to an Amazon DocumentDB endpoint.

You used the incorrect credentials to connect to the cluster

Make sure that you enter the correct username and password when you connect to the cluster. If you forgot your password, then you can modify the Amazon DocumentDB cluster to reset the password.

Your application doesn't use TLS encrypted connection

By default, Amazon DocumentDB turns on encryption in transit for all clusters. If your application doesn't use TLS/SSL connections, then you can modify the tls cluster parameter value to turn off TLS.

You receive the "unable to get local issuer certificate" error message

You might get the "unable to get local issuer certificate" error message for a MongoDB driver that's compatible with the certificate authority (CA) certificate. If you connect to the cluster when TLS is activated, then make sure that you use the latest public certificate bundle.

You can't connect to your instance after you reboot

When you reboot an instance, the private IP address of the instance might change and cause connectivity issues. It's a best practice to use cluster or instance endpoints.

You can't connect after a number of connections

If you can no longer connect, then your instance might have reached the maximum quota of database connections for its instance class. To allow more connections, upgrade the instance class.

It's a best practice to troubleshoot connection management from the client side. Check your connection pooling and the related timeout settings. The settings must be sufficient for you to manage the number of connections to your cluster. Adjust the settings so that you don't reach your connection quota.

You can't use AWS Client VPN to connect from a local system

You might fail to connect to your cluster from a local system when you use a VPN. AWS Client VPN lets you connect to your remote network from your VPC and configure routing to pass traffic through the connection. Make sure that you correctly configure AWS Client VPN.

You experience intermittent connectivity issues

If your application experiences intermittent connectivity issues, then check whether there's a heavy workload on your cluster. For example, review Amazon CloudWatch metrics, such as VolumeWriteIOPs, VolumeReadIOPs, OpcountersCommand, CPUUtilization, and DBLoad for spikes that might be because of resource bottlenecks. Suboptimal query plans might cause user queries to run slowly, and resource contention might block user queries. Use Performance Insights and profiler logs to find the queries that cause this issue.

Important: Performance Insights will reach its end of life on June 30, 2026. You can upgrade to the Advanced mode of Database insights before June 30, 2026. If you don't upgrade, then DB clusters that use Performance Insights will default to the Standard mode of Database Insights. Only the Advanced mode of Database Insights will support execution plans and on-demand analysis. If your clusters default to the Standard mode, then you might not be able to use these features on the console. To turn on the Advanced mode, see Turning on the Advanced mode of Database Insights for Amazon RDS and Turning on the Advanced mode of Database Insights for Amazon Aurora.

Related information

Troubleshoot connection issues

Monitoring Amazon DocumentDB with CloudWatch

Security in Amazon DocumentDB