Amazon DocumentDB
Developer Guide

The AWS Documentation website is getting a new look!
Try it now and let us know what you think. Switch to the new look >>

You can return to the original look by selecting English in the language selector above.

Troubleshooting Amazon DocumentDB

The following sections provide information about how to troubleshoot problems that you might encounter when using Amazon DocumentDB (with MongoDB compatibility).

Important

The certificate authority (CA) certificate for Amazon DocumentDB clusters is being updated. As of September 1, 2019, the new CA bundle (rds-combined-ca-bundle.pem) contains both the old CA certificate (rds-ca-2015-root.pem) and the new CA certificate (rds-ca-2019-root.pem).

To avoid an interruption in connectivity between your application and your Amazon DocumentDB clusters, take the following actions before February 5, 2020:

  1. Download the new CA certificate (rds-ca-2019-root.pem) and update your application to use the new CA certificate to create TLS connections to Amazon DocumentDB.

  2. Modify the instances in your Amazon DocumentDB clusters to update the server certificate.

As of November 1, 2019, all new Amazon DocumentDB instances you create will use the new server certificate and will require the new CA certificate to create TLS connections. For more information, see Updating Your Amazon DocumentDB TLS Certificates.

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.

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

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

Output from this operation looks something like the following (JSON format).

[ "sample-cluster.cluster-corcjozrlsfc.us-east-1.docdb.amazonaws.com" ]

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

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

 

Output from this operation looks something like the following (JSON format).

[ [ "us-east-1a" ] ]

 

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.

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

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

aws ec2 describe-instances \ --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.

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

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

aws docdb describe-db-clusters \ --db-cluster-identifier sample-cluster \ --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):

nc -zv cluster-endpoint port

For example, the following shows a sample operation and the return value:

nc -zv docdbTest.d4c7nm7stsfc0.us-west-2.docdb.amazonaws.com 27017 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.

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

The output looks like this:

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

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

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

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

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

For more information, see Managing Amazon DocumentDB Endpoints.

Identifying Billable Amazon DocumentDB Resources

As a fully managed database service, Amazon DocumentDB charges for instances, storage, I/Os, backups, and data transfer. For more information, see Amazon DocumentDB (with MongoDB compatibility) pricing.

To discover billable resources in your account and potentially delete the resources, you can use the AWS Management Console or AWS CLI.

Using the AWS Management Console

Using the AWS Management Console, you can discover the Amazon DocumentDB clusters, instances, and snapshots that you have provisioned for a given AWS Region.

To discover clusters, instances, and snapshots

  1. Sign in to the AWS Management Console, and open the Amazon DocumentDB console at https://console.aws.amazon.com/docdb.

  2. To discover billable resources in a Region other than your default Region, in the upper-right corner of the screen, choose the AWS Region that you want to search.

    
                     Console screenshot showing N Virginia in the region selector.
  3. In the navigation pane, choose the type of billable resource that you're interested in: Clusters, Instances, or Snapshots.

    
                     Console screenshot showing clusters, instances, and snapshots in the navigation pane.
  4. All your provisioned clusters, instances, or snapshots for the Region are listed in the right pane. You will be charged for clusters, instances, and snapshots.

Using the AWS CLI

Using the AWS CLI, you can discover the Amazon DocumentDB clusters, instances, and snapshots that you have provisioned for a given AWS Region.

To discover clusters and instances

The following code lists all your clusters and instances for the specified Region. If you want to search for clusters and instances in your default Region, you can omit the --region parameter.

For Linux, macOS, or Unix:

aws docdb describe-db-clusters \ --region us-east-1 \ --query 'DBClusters[?Engine==`docdb`]' | \ grep -e "DBClusterIdentifier" -e "DBInstanceIdentifier"

For Windows:

aws docdb describe-db-clusters ^ --region us-east-1 ^ --query 'DBClusters[?Engine==`docdb`]' | ^ grep -e "DBClusterIdentifier" -e "DBInstanceIdentifier"

Output from this operation looks something like the following (JSON format).

"DBClusterIdentifier": "docdb-2019-01-09-23-55-38", "DBInstanceIdentifier": "docdb-2019-01-09-23-55-38", "DBInstanceIdentifier": "docdb-2019-01-09-23-55-382", "DBClusterIdentifier": "sample-cluster", "DBClusterIdentifier": "sample-cluster2",

To discover snapshots

The following code lists all your snapshots for the specified Region. If you want to search for snapshots in your default Region, you can omit the --region parameter.

For Linux, macOS, or Unix:

aws docdb describe-db-cluster-snapshots \ --region us-east-1 \ --query 'DBClusterSnapshots[?Engine==`docdb`].[DBClusterSnapshotIdentifier,SnapshotType]'

For Windows:

aws docdb describe-db-cluster-snapshots ^ --region us-east-1 ^ --query 'DBClusterSnapshots[?Engine==`docdb`].[DBClusterSnapshotIdentifier,SnapshotType]'

Output from this operation looks something like the following (JSON format).

[ [ "rds:docdb-2019-01-09-23-55-38-2019-02-13-00-06", "automated" ], [ "test-snap", "manual" ] ]

You only need to delete manual snapshots. Automated snapshots are deleted when you delete the cluster.

Deleting Unwanted Billable Resources

To delete a cluster, you must first delete all the instances in the cluster.

Index Creation

The following topics address what to do if your index or background index build fails.

Index Build Fails

Amazon DocumentDB utilizes local storage on an instance as part of the index creation process. You can monitor this disk usage using the FreeLocalStorage CloudWatch metric (CloudWatch -> Metrics -> DocDB -> Instance Metrics). When an index build consumes all of the local disk and fails, you will receive an error. When migrating data to Amazon DocumentDB, we encourage you to create indexes first and then insert the data. For more information on migration strategies and creating indexes, see Migrating to Amazon DocumentDB in the Amazon DocumentDB documentation and the blog: Migrate from MongoDB to Amazon DocumentDB using the offline method.

When creating indexes on an existing cluster, if the index build is taking longer than expected or is failing, we recommend that you scale-up the instance to create the index then, after the index is created, scale back down. Amazon DocumentDB enables you to quickly scale instance sizes in minutes using the AWS Management Console or the AWS CLI. For more information, see Managing Instance Classes. With per-second instance pricing, you only pay for the resource you use up to the second.

Background Index Build Fails

Amazon DocumentDB allows only one background index build to occur on a collection at any given time. If DDL (Data Definition Language) operations such as createIndex() or dropIndex() occur on the same collection during a background index build, the background index build fails.