How can I troubleshoot common issues that I encounter when I use mongorestore with an Amazon DocumentDB cluster?

Short description

The mongorestore utility lets you restore a BSON backup of a database that was created with the mongodump utility. For more information see mongorestore and mongodump on the MongoDB website.

See the following syntax:

mongorestore --ssl \  
    --host="tutorialCluster.us-east-1.docdb.amazonaws.com:27017" \  
    --numParallelCollections 4 \  
    --username=<yourUsername> \  
    --sslCAFile global-bundle.pem <mongodumpFileToBeRestored>

When you use mongorestore with Amazon DocumentDB clusters, you can encounter the following common issues:

• Error: "fatal error: runtime: out of memory"
• Error: "Failed: error getting auth version of server: Feature not supported: getParameter"
• Error: "Document can't have '.' in field names"
• Connectivity issues to the Amazon DocumentDB cluster
• Slow mongorestore restore process

Resolution

Error: "fatal error: runtime: out of memory"

This error occurs when the source that runs the mongorestore command is out of memory. If you run the mongorestore command on an Amazon Elastic Compute Cloud (Amazon EC2) instance, then allocate more swap or scale the instance class of the EC2 instance.

You can also reduce the number of collections that mongorestore restores at the same time. To do this, set the numParallelCollections option to a lower value The default value for numParallelCollections is 4.

Error: "Document can't have '.' in field names"

Amazon DocumentDB doesn't support the use of certain characters in the document field name. This includes “.” and the prefix "$". If you use these characters in the document field name of the mongodump file that mongorestore uses to restore, then you encounter an error. For more information, see Field name restrictions.

To prevent this error, make sure that dump files don't contain restricted characters before you restore. Rename the fields and update the application clients so that the unsupported characters are removed.

Error: "Failed: error getting auth version of server: Feature not supported: getParameter"

This error occurs when mongorestore restores a dump file that contains an admin database. Amazon DocumentDB doesn't support admin or local databases. It also doesn't support the MongoDB system.* or startup_log collections.

To resolve this issue, use --nsExclude to exclude the matching namespaces from the restore option in the mongorestore command. For example, run --nsExclude=“admin.*. For more information, see --nsExclude on the MongoDB website.

Connectivity issues to Amazon DocumentDB cluster

The source that issues the mongorestore command must connect to the Amazon DocumentDB cluster that contains the dump file that you're restoring. The connection to an Amazon DocumentDB cluster can fail because of the virtual private cloud (VPC) configuration, endpoint resolution, or SSL/TLS authentication.

For more information, see How do I resolve problems connecting to my Amazon DocumentDB cluster? and Connection issues.

Slow mongorestore restore process

As part of its process, mongorestore recreates all data files and then rebuilds indexes. The size of the database contributes to the time it takes mongorestore to perform a restore. To improve the mongorestore performance, implement the following best practices:

• Instead of a remote host, run mongorestore on an instance that's in same VPC as the target Amazon DocumentDB cluster to avoid additional network hopping. Make sure that the instance that you use to run the mongorestore process has sufficient CPU and memory to handle the operation.
• The numInsertionWorkersPerCollection option determines the number of insertion workers to run concurrently for each collection. The default value is 1, but you can increase the value to increase the speed of large imports. It's a best practice to start with one worker for each vCPU on your Amazon DocumentDB cluster's primary instance.
• The numParallelCollections option determines the number of collections that mongorestore restores at the same time. The default value is 4, but you can increase the value to increase the speed of the mongorestore process.
• Before you import large datasets, create the indexes on the target Amazon DocumentDB cluster. Use the Amazon DocumentDB index tool on the GitHub website. During the data load, indexing operations are done at the same time. When you create your indexes first, you provide the --noIndexRestore option and skip the index creation step.
• Confirm that the primary instance of the target Amazon DocumentDB cluster isn't throttling and has sufficient resources, such as memory and CPU. Use Amazon Cloudwatch metrics, performance and resource utilization diagnostics, and Performance Insights to monitor resource utilization for your Amazon DocumentDB cluster. If it's required, then scale up the primary instance. Scale down the instance after the restore is complete.

Related information

Migrating to Amazon DocumentDB

Functional differences: Amazon DocumentDB and MongoDB