Connection Issues

Having trouble connecting? Here are some common scenarios and how to resolve them.

Cannot Connect to an Amazon DocumentDB Endpoint

When you try to connect to Amazon DocumentDB, the following is one of the most common error messages that you might receive.

  1. connecting to: mongodb://docdb-2018-11-08-21-47-27.cluster-ccuszbx3pn5e.us-east-
  2. 1.docdb.amazonaws.com:27017/
  3. 2018-11-14T14:33:46.451-0800 W NETWORK [thread1] Failed to connect to
  4. 172.31.91.193:27017 after 5000ms milliseconds, giving up.
  5. 2018-11-14T14:33:46.452-0800 E QUERY [thread1] Error: couldn't connect to server
  6. docdb-2018-11-08-21-47-27.cluster-ccuszbx3pn5e.us-east-1.docdb.amazonaws.com:27017,
  7. connection attempt failed :
  8. connect@src/mongo/shell/mongo.js:237:13
  9. @(connect):1:6
  10. exception: connect failed

What this error message typically means is that your client (the mongo shell in this example) cannot access the Amazon DocumentDB endpoint. This might be the case for several reasons:

Connecting from Public Endpoints

You are trying to connect to an Amazon DocumentDB cluster directly from your laptop or local development machine.

Trying to connect to an Amazon DocumentDB cluster directly from a public endpoint, such as your laptop or local development machine, will fail. Amazon DocumentDB is virtual private cloud (VPC)-only and does not currently support public endpoints. Thus, you can’t connect directly to your Amazon DocumentDB cluster from your laptop or local development environment outside of your VPC.

To connect to an Amazon DocumentDB cluster from outside an Amazon VPC, you can use an SSH tunnel. For more information, see Connecting to an Amazon DocumentDB Cluster from Outside an Amazon VPC. Additionally, if your development environment is in a different Amazon VPC, you can also use VPC Peering and connect to your Amazon DocumentDB cluster from another Amazon VPC in the same region or a different region.

Cross Region Connections

You are trying to connect to an Amazon DocumentDB cluster in another region.

If you try to connect to an Amazon DocumentDB cluster from an Amazon EC2 instance in a Region other than the cluster’s Region—for example, trying to connect to a cluster in US East (N. Virginia) Region (us-east-1) from US West (Oregon) Region (us-west-2)—the connection will fail.

To verify the Region of your Amazon DocumentDB cluster, run the following command. The Region is in the endpoint.

  1. aws docdb describe-db-clusters \
  2.    --db-cluster-identifier sample-cluster \
  3.    --query 'DBClusters[*].Endpoint'

Output from this operation looks something like the following.

  1. [
  2.     "sample-cluster.node.us-east-1.docdb.amazonaws.com"
  3. ]

To verify the Region of your EC2 instance, run the following command.

  1.  aws ec2 describe-instances \
  2.      --query 'Reservations[*].Instances[*].Placement.AvailabilityZone'

Output from this operation looks something like the following.

  1. [
  2.     [
  3.         "us-east-1a"
  4.     ]
  5. ]

Connecting from Different Amazon VPCs

You are trying to connect to an Amazon DocumentDB cluster from a VPC that is different than the Amazon VPC your cluster is deployed to.

If both your Amazon DocumentDB cluster and Amazon EC2 instance are in the same AWS Region, but not in the same Amazon VPC, you cannot connect directly to your Amazon DocumentDB cluster unless VPC Peering is enabled between the two Amazon VPCs.

To verify the Amazon VPC of your Amazon DocumentDB instance, run the following command.

  1. aws docdb describe-db-instances \
  2.    --db-instance-identifier sample-instance \
  3.    --query 'DBInstances[*].DBSubnetGroup.VpcId'

To verify the Amazon VPC of your Amazon EC2 instance, run the following command.

  1. aws ec2 describe-instances \
  2.    --query 'Reservations[*].Instances[*].VpcId'

Security Group Blocks Inbound Connections

You are trying to connect to an Amazon DocumentDB cluster, and the cluster’s security group does not allow inbound connections on the cluster’s port (default port: 27017).

Suppose that your Amazon DocumentDB cluster and Amazon EC2 instance are both in the same Region and Amazon VPC and use the same Amazon VPC security group. If you can’t connect to your Amazon DocumentDB cluster, the likely cause is that your security group (that is, firewall) for your cluster doesn’t allow inbound connections on the port you chose for your Amazon DocumentDB cluster (default port is 27017).

To verify the port for your Amazon DocumentDB cluster, run the following command.

  1. aws docdb describe-db-clusters \
  2.    --db-cluster-identifier sample-cluster \
  3.    --query 'DBClusters[*].[DBClusterIdentifier,Port]'

To get your Amazon DocumentDB security group for your cluster, run the following command.

  1. aws docdb describe-db-clusters \
  2.    --db-cluster-identifier sample-cluster \
  3.    --query 'DBClusters[*].[VpcSecurityGroups[*],VpcSecurityGroupId]'

To check the inbound rules for your security group, see the following topics in the Amazon EC2 documentation:

Testing a Connection to an Amazon DocumentDB Instance

You can test your connection to a cluster using common Linux or Windows tools.

From a Linux or Unix terminal, test the connection by entering the following (replace cluster-endpoint with the endpoint, and replace port with the port of your instance):

  1. nc -zv cluster-endpoint port

The following is an example of a sample operation and the return value:

  1. nc -zv docdbTest.d4c7nm7stsfc0.us-west-2.docdb.amazonaws.com 27017
  3. Connection to docdbTest.d4c7nm7stsfc0.us-west-2.docdb.amazonaws.com 27017 port [tcp/*] succeeded!

Connecting to an Invalid Endpoint

When connecting to an Amazon DocumentDB cluster and you use a cluster endpoint that is not valid, an error similar to the following appears.

  1. mongo --ssl \
  2.    --host sample-cluster.node.us-east-1.docdb.amazonaws.com:27017 \
  3.    --sslCAFile rds-combined-ca-bundle.pem \
  4.    --username <user-name> \
  5.    --password <password>

The output looks like this:

  1. MongoDB shell version v3.6
  2. connecting to: mongodb://sample-cluster.node.us-east-1.docdb.amazonaws.com:27017/
  3. 2018-11-14T17:21:18.516-0800 I NETWORK [thread1] getaddrinfo("sample-cluster.node.us-east-1.docdb.amazonaws.com") failed: 
  4. nodename nor servname provided, or not known 2018-11-14T17:21:18.537-0800 E QUERY [thread1] Error: couldn't initialize
  5. connection to host sample-cluster.node.us-east-1.docdb.amazonaws.com, address is invalid :
  6. connect@src/mongo/shell/mongo.js:237:13@(connect):1:6
  7. exception: connect failed

To get the valid endpoint for a cluster, run the following command:

  1. aws docdb describe-db-clusters \
  2.    --db-cluster-identifier sample-cluster \
  3.    --query 'DBClusters[*].[Endpoint,Port]'

To get the valid endpoint for an instance, run the following command:

  1. aws docdb describe-db-instances \
  2.    --db-instance-identifier sample-instance \
  3.    --query 'DBInstances[*].[Endpoint.Address,Endpoint.Port]'

For more information, see Understanding Amazon DocumentDB Endpoints.