Docs Menu

Docs HomeView & Analyze DataMongoDB Compass

Compass Connection Errors

On this page

  • MongoDB Not Running on the Provided Host and Port
  • Insert Document Button Disabled and Cannot Modify Documents
  • Connection to Cluster Shard Closed
  • Not Primary or Secondary is Not Writable
  • Authentication Failed
  • Check the Compass Logs
  • Additional Resources

The sections on this page list common errors seen when connecting to MongoDB Compass and provide possible solutions.

Your connection failed when Compass attempted to connect to your database on the specified host and port.

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.

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:

When using Compass, you may be in a state where you cannot perform any write operations, and can only read data.

When you are in this state:

  • The Create Collection and Insert Document buttons are disabled.

  • You cannot modify any of your documents.

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.

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 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

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.

This error means that the connection to your MongoDB cluster was closed before the initial setup completed.

You may see an error in MongoDB Compass similar to the following:

connection 3 to cluster0-shard-00-00-a1b2c.mongodb.net:27017 closed

The most common source of this error is a missing Atlas IP whitelist entry for the public IP address where Compass is running.

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).

Tip

See also:

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

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.

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

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.

Tip

See also:

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

When you attempt to connect to your cluster using Compass, you may encounter an error message stating Authentication Failed.

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.

  • 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.

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.

←  Retrieve Compass LogsKeyboard Shortcuts →