How do I connect to an Amazon DocumentDB 3.6/4.0 cluster from AWS CloudShell when mongosh fails with a wire version error?

Problem

When you use the "Connect to cluster" button in the Amazon DocumentDB console, AWS CloudShell auto-installs mongosh (the modern MongoDB shell). However, connecting to a DocumentDB 3.6 or 4.0 cluster fails with the following error:

MongoServerSelectionError: Server at <endpoint>:<port> reports maximumWireVersion 7,
but this version of the Node.js Driver requires at least 8 (MongoDB 4.2)

Note: For DocumentDB 3.6 clusters, the error reports maximumWireVersion 6 instead of 7.

Root Cause

mongosh requires wire protocol version 8 or higher (MongoDB 4.2+). DocumentDB 3.6 and 4.0 do not meet this requirement:

• DocumentDB 3.6 — wire protocol version 6
• DocumentDB 4.0 — wire protocol version 7
• mongosh minimum requirement — wire protocol version 8

Resolution

Install the legacy mongo shell (v5.0) in AWS CloudShell. This version supports wire protocol versions 6 and 7, making it compatible with both DocumentDB 3.6 and 4.0.

1. Add the MongoDB 5.0 repository:

echo -e "[mongodb-org-5.0] \nname=MongoDB Repository\nbaseurl=https://repo.mongodb.org/yum/amazon/2023/mongodb-org/5.0/x86_64/\ngpgcheck=1 \nenabled=1 \ngpgkey=https://pgp.mongodb.com/server-5.0.asc" | sudo tee /etc/yum.repos.d/mongodb-org-5.0.repo

2. Install the legacy mongo shell:

sudo yum install -y mongodb-org-shell

3. Verify the installation:

mongo --version

Expected output: MongoDB shell version v5.0.x

4. Connect to your DocumentDB cluster:

With TLS enabled (default):

wget https://truststore.pki.rds.amazonaws.com/global/global-bundle.pem

mongo --ssl \
  --host <endpoint>:<port> \
  --sslCAFile global-bundle.pem \
  --username <user> \
  --password <password>

With TLS disabled:

mongo --host <endpoint>:<port> \
  --username <user> \
  --password <password>

Important Notes

• CloudShell environments are ephemeral. If the environment expires due to inactivity, you will need to repeat the installation steps.
• This workaround applies to both DocumentDB 3.6 and DocumentDB 4.0 clusters. Upgrading to DocumentDB 5.0 allows mongosh to work natively without this workaround.
• The yum install command requires outbound internet access from CloudShell. If your CloudShell VPC environment does not have a NAT gateway configured, the install will hang. In that case, either configure a NAT gateway for your private subnet, or upload the mongodb-org-shell RPM to an S3 bucket and download it in CloudShell using an S3 VPC Gateway Endpoint (aws s3 cp s3://your-bucket/mongodb-org-shell-5.0.x.rpm ~/ then sudo yum localinstall -y ~/mongodb-org-shell-5.0.*.rpm).
• The legacy mongo shell (v5.0) will eventually reach end-of-life. Plan to upgrade your DocumentDB cluster version when feasible.

References

• Connecting to an Amazon DocumentDB Cluster: https://docs.aws.amazon.com/documentdb/latest/developerguide/connect.html