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 same VPC as your instance.

But you can use VPC peering or Transit Gateway to access Amazon DocumentDB from EC2 instances or other AWS services in different VPCs or Regions. But if you need to access your Amazon DocumentDB cluster from outside of the AWS network, then use SSH tunneling or AWS Client VPN.

Resolution

Note: If you receive errors when you run AWS Command Line Interface (AWS CLI) commands, then make sure that you use the most recent AWS CLI version.

There are a number of reasons you might experience issues when you try to connect to an Amazon DocumentDB cluster. Use the following steps to troubleshoot the most common root causes.

DB instance isn't in the available state

Check that your Amazon DocumentDB cluster has at least one instance and cluster in an available state. If your instances aren't in available states, then they can't accept connections. For more information, see Monitor an Amazon DocumentDB cluster's status and Monitor an Amazon DocumentDB instance's status.

The source doesn't have authorized access to the cluster

Confirm that the source that you use to connect to the instance is authorized to access the cluster. Your instance must have access to the cluster in your network access control lists (ACLs), local firewalls, and security group rules. Be sure that traffic from the source that connects to your DB instance isn't blocked by one or more of the following:

• Amazon Virtual Private Cloud (Amazon VPC) security groups associated with the DB instance. If necessary, add rules to the security group associated with the VPC that allows traffic related to the source in and out of the DB instance. You can specify an IP address, a range of IP addresses, or another VPC security group.
• Network ACL rules. If you use Network ACLs in your VPC, then be sure that they have rules that allow inbound and outbound traffic to and from the DB instance.
• Network or local firewalls. Check if your network allows traffic to and from the ports that the DB instance uses for inbound and outbound communication.

Amazon VPC subnet route tables don't allow traffic

Your Amazon VPC subnet's route table must allow traffic from your machine or instance. Confirm that the subnets associated with each DB instance are associated with the same or similar route tables.

If your primary DB instance fails over to a standby replica that's associated with a different route table, then traffic might not route correctly. If that traffic was previously routed without any issues, then check that it's still routed correctly.

Incorrect DNS name or endpoint

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

For example, use nslookup to the DB instance endpoint from an EC2 instance within the VPC:

nslookup docdb-2022-12-16-09-10-582.cuh2dlyxxxxx.us-east-1.docdb.amazonaws.com
Server: x.x.x.x
Address: x.x.x.x#53
Non-authoritative answer:
Name: docdb-2022-12-16-09-10-582.cuh2dlyrdizy.us-east-1.docdb.amazonaws.com
Address: x.x.x.x

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

Check if a connection is established

Run one of the following commands to verify your connection:

telnet <DocDB endpoint> <port number>

nc -zv <DocDB endpoint> <port number>

If either the telnet or the nc command succeeds, then a network connection is established. This means that the issue is likely caused by the user authentication to the database, such as user name and password.

Confirm the credentials that you use to connect

Confirm that you enter the correct username and password when you connect to the cluster. If you forget your password, you can modify the Amazon DocumentDB cluster to reset the password.

Turn off TLS configuration

By default, TLS configuration is turned on for Amazon DocumentDB clusters. If your application doesn't use TLS/SSL connections, then turn off the TLS configuration from the custom Amazon DocumentDB cluster parameter group. For more information, see Manage Amazon DocumentDB cluster parameter groups.

Note: TLS is a static parameter that requires you to reboot the cluster for the cluster parameter group changes to take effect. For more information, see Modify Amazon DocumentDB cluster parameters.

Troubleshoot other use cases

Can't get local issuer certificate error

You might receive an "unable to get local issuer certificate" error caused by MongoDB driver compatibility with the CA certificate. Make sure that you use the correct parameters as detailed in Connect with TLS turned on.

Can't connect to your instance post reboot

You might be unable to connect to your instance after a reboot. When you reboot an instance, the private IP address of the instance might change. This can caused connectivity issues. It's a best practice to use cluster or instance endpoints instead of using the DNS resolved IP addresses of the Amazon DocumentDB resource.

Authentication failed errors

You might receive an "Authentication failed" error when you connect to your instance. This error is caused by password issues such as use of an incorrect password or incorrect username. Follow the steps below to resolve this error:

1. Confirm that the correct username and password is provided.
2. Enter the password manually instead of using a copy and paste method.
3. Reset the password from the Amazon DocumentDB console or using the AWS CLI.

Can't connect after a number of connections

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

It's a best practice to investigate connection management from the client side. Check that connection pooling and the related timeout settings are set correctly. Settings must be sufficient for you to manage the number of connections to your Amazon DocumentDB cluster. Settings must also prevent you from hitting the connection limit.

Can't connect from a local system using AWS Client VPN

You might be unable to connect to your Amazon DocumentDB cluster from a local system when you use a virtual private network (VPN). Make sure that you use the AWS Client VPN correctly. AWS Client VPN allows you to connect to your remote network from your VPC, and configures routing to pass traffic through the connection.

Intermittent connectivity issues

If your application faces an intermittent connectivity issue, then check if there's heavy workload on your cluster. For example, review Amazon CloudWatch metrics such as VolumeWriteIOPs, VolumeReadIOPs, OpcountersCommand, and CPUUtilization.

If you observe spikes in these CloudWatch metrics, then your connection issues might be caused by blocking. User queries can run slowly because of a suboptimal query plans or can be blocked by resource contention. Use Performance Insights and Profiler logs to find the query that caused this issue.

Related information

Connection issues

Use Amazon EC2 to connect

Monitor Amazon DocumentDB with CloudWatch

Security in Amazon DocumentDB