Navigation

Compass Connection Errors

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:

  1. Navigate to your Atlas Clusters view.

  2. Click Connect for your desired cluster.

  3. Click Connect with MongoDB Compass.

  4. Copy the provided connection string.

  5. Open MongoDB Compass.

  6. Click Yes to auto-fill the connection settings.

    Image showing autofill connection dialog

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:

  1. Use the Context dropdown in the top-left of Atlas to select your desired Atlas project.
  2. Click the Security tab.
  3. Click the IP Whitelist menu option.
  4. If your IP address is not in the whitelist, click Add IP Address.
  5. Click Add Current IP Address.
  6. Click Confirm.

Atlas recognizes which entries in the whitelist include your current IP address, and appends these addresses with (includes your current IP address).

See Also

For more information on configuring whitelist entries, see Configure Whitelist Entries in the Atlas documentation.

Not Master 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:

  1. Navigate to your Atlas Clusters view.

  2. Click Connect for your desired cluster.

  3. Click Connect with MongoDB Compass.

  4. Copy the provided connection string.

  5. Open MongoDB Compass.

  6. Click Yes to auto-fill the connection settings.

    Image showing autofill connection dialog

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.

See Also

For more information on read preferences, see Read Preference in the MongoDB manual.

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.
←   Troubleshooting FAQ  →