Compass Connection Errors
On this page
The sections on this page list common errors seen when connecting to MongoDB Compass and provide possible solutions.
MongoDB Not Running on the Provided Host and Port
Your connection failed when Compass attempted to connect to your database on the specified host and port.
Likely Causes
This error often occurs when:
You provide no hostname or an invalid hostname to the Compass connect dialog.
The destination server rejects a connection on an incorrect port.
Your MongoDB cluster or server has been shutdown or the server hostname has changed.
You have a firewall actively blocking connections to/from your local network.
Solutions
The solution to this issue may depend on how your MongoDB environment is configured. Select the appropriate tab for your MongoDB environment to view possible solutions:
Try these solutions if you have a self-hosted MongoDB server, replica set, or cluster.
Ensure Your MongoDB Instance is Running
Compass must connect to a running MongoDB instance. Make sure you have installed MongoDB and have a running mongod process. You should also check that the port where your MongoDB instance is running matches the port you provide in the Compass connect dialog.
Required Config File Setting: bindIp
If you recently installed the MongoDB database server and are
unable to establish an initial connection to that server,
verify that you have specified a valid net.bindIp
setting in your server configuration file.
Hostname and Port
If your self-hosted server is listening on an external network
via net.bindIp, verify that you have specified your
Hostname and Port correctly in the
Compass connect dialog.
MongoDB Server Moved or Shutdown
It is possible that your MongoDB cluster or server has been shutdown or had its hostname has changed. Contact your database administrator for updates on the status of your database.
Firewall
If you believe your firewall may be actively blocking connections to the port(s) your database(s) are operating on, try connecting from a different location, such as a home or internet cafe network. You can also visit http://portquiz.net/ to test your connection to different ports.
If you are connecting to an Atlas cluster, first follow the procedure described in the Connect via Compass page in the Atlas documentation. The steps on that page will help ensure that your connection settings are optimized for Atlas.
MongoDB Server Moved or Shutdown
It is possible that your MongoDB cluster or server has been shutdown or had its hostname has changed. Contact your database administrator for updates on the status of your database.
Firewall
If you believe your firewall may be actively blocking connections to your database, try connecting from a different location, such as a home or internet cafe network.
Atlas clusters operate on port 27017. You must be able to access this port to access your cluster. To check if your local network blocks connections to port 27017, visit http://portquiz.net:27017/.
Atlas IP Whitelist Does Not Include Your Address
Atlas only allows connections to a cluster from addresses listed in the project IP whitelist. Ensure that you have whitelisted your IP address so you can connect to your cluster.
Insert Document Button Disabled and Cannot Modify Documents
When using Compass, you may be in a state where you cannot perform any write operations, and can only read data.
Possible Observations
When you are in this state:
The Create Collection and Insert Document buttons are disabled.
You cannot modify any of your documents.
Likely Cause
There are two likely causes for this behavior:
You are connected to a secondary member of your cluster, which does not support write operations.
You are using Compass Readonly edition, which does not support write operations.
Solutions
Check Read Preference Setting
In the Compass connection dialog, set your Read Preference to Primary. This will ensure that you connect to your cluster's primary member, which supports write operations.
Check Replica Set Name
Check that your Replica Set Name is accurate. Compass is only able to identify the primary correctly if the replica set name is accurate.
If your cluster is hosted in Atlas, you can obtain the correct replica set name using the following procedure:
Navigate to your Atlas Clusters view.
Click Connect for your desired cluster.
Click Connect with MongoDB Compass.
Copy the provided connection string.
Open MongoDB Compass.
Click Yes to auto-fill the connection settings.
Check Your Compass Edition
You cannot perform write operations in Compass Readonly edition. You can check your Compass edition by opening the top-level Compass dropdown menu and selecting About MongoDB Compass.
To perform write operations, you must download a different edition of MongoDB Compass. For more information on the differences between Compass editions, see Capabilities of Compass Editions.
Connection to Cluster Shard Closed
This error means that the connection to your MongoDB cluster was closed before the initial setup completed.
Possible Observations
You may see an error in MongoDB Compass similar to the following:
connection 3 to cluster0-shard-00-00-a1b2c.mongodb.net:27017 closed
Likely Cause
The most common source of this error is a missing Atlas IP whitelist entry for the public IP address where Compass is running.
Solution
Ensure the public IP address where Compass is running is included in your Atlas project's IP whitelist.
To configure your Atlas whitelist:
Use the Context dropdown in the top-left of Atlas to select your desired Atlas project.
Click the Security tab.
Click the IP Whitelist menu option.
If your IP address is not in the whitelist, click Add IP Address.
Click Add Current IP Address.
Click Confirm.
Atlas recognizes which entries in the whitelist include your current IP address, and appends these addresses with (includes your current IP address).
Tip
See also:
For more information on configuring whitelist entries, see Configure Whitelist Entries in the Atlas documentation.
Not Primary or Secondary is Not Writable
This error message indicates that you have connected to one of the secondary members of a replica set without providing the correct replica set name and requiring a connection to a primary in your Read Preference.
Solutions
Verify Atlas Replica Set Name
You should ensure that you are providing the correct replica set name in the Compass connect dialog.
If your cluster is hosted in Atlas, you can obtain the correct replica set name using the following procedure:
Navigate to your Atlas Clusters view.
Click Connect for your desired cluster.
Click Connect with MongoDB Compass.
Copy the provided connection string.
Open MongoDB Compass.
Click Yes to auto-fill the connection settings.
Allow Compass to Connect to the Secondary
Another approach to resolving this error is to allow Compass to connect to a secondary cluster member. Change your Read Preference to either Primary Preferred or Secondary Preferred in your connection settings. This should allow you to bypass this error and connect.
Note
When you connect to a secondary cluster member, you cannot create or modify documents, indexes, or databases. Only use this solution when you do not need to perform any write operations.
Authentication Failed
When you attempt to connect to your cluster using Compass, you may encounter an error message stating Authentication Failed.
Likely Causes
This error message is often the result of one of five conditions:
Your Password is missing after autofilling your connection details from a copied connection string. Compass requires you to manually enter your password in the connection dialog as a security precaution.
Your Username and/or Password are incorrect.
You have not configured any MongoDB users for your Atlas cluster.
You did not select the correct Authentication method.
You did not specify the correct Authentication Database. This setting corresponds to the authSource connection string option.
Note
For Atlas clusters, the Authentication Database is usually
admin.
Solutions
Ensure you provided the correct Username and Password.
Ensure that the MongoDB user you are authenticating as exists.
Verify your Authentication Database and authentication mechanism.
Verify that your selected authentication mechanism is supported by your MongoDB database.
Check the Compass Logs
The Compass logs can provide additional information on connection errors. You may find more detailed error messages to help diagnose your issue. For more information, see Retrieve Compass Logs.