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

Resolution

"fatal error: runtime: out of memory" error

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.

"Document can't have '.' in field names" error

Amazon DocumentDB doesn't support certain characters in document field names, including "." 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 Dollar($) and dot(.) in field names.

To prevent this error, check your dump files for restricted characters before you restore them. Rename the fields and update the application clients to remove the unsupported characters.

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

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 want to restore. The connection to an Amazon DocumentDB cluster might fail because of the virtual private cloud (VPC) configuration, endpoint resolution, or SSL/TLS authentication.

For more information, see Why can't I connect to my Amazon DocumentDB cluster? and Troubleshooting 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 determines the amount of 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.
• To control how many collections mongorestore restores simultaneously, use the numParallelCollections option. The default value is 4, but you can increase the value to increase the speed of the mongorestore process.
• Create your indexes on the target Amazon DocumentDB cluster before you import large datasets. Use the Amazon DocumentDB index tool on the GitHub website. Indexing operations run at the same time during the data load. When you create your indexes first, you can use the --noIndexRestore option and skip the index creation step.
• Monitor your target Amazon DocumentDB cluster’s primary instance to make sure that it doesn't throttle and it has enough resources including memory and CPU. You can use Amazon Cloudwatch metrics, performance and resource utilization diagnostics, and Performance Insights to track resource utilization. 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

mongorestore on the MongoDB website

mongodump on the MongoDB website