Skip to content

MongoDB Troubleshooting

This page documents the known problems with a MongoDB datastore and the steps to resolve them. A MongoDB connection depends on three things in sequence, a valid set of connection settings, reaching the servers, and signing in, and the first sections below cover them in that order. The last section covers what can go wrong once the connection works and a collection is read.

Connection Settings

These are refused before Qualytics tries to reach MongoDB, so the message appears as soon as you test the connection.

The Host Is Refused

The test or the save fails with a message that the host must be a host[:port] list, and that credentials belong in the user and password fields.

Cause: Host contains something other than host names and ports, such as a user:password@ prefix, a mongodb:// scheme, a /database path, a ?option=value query, or a space.

Resolution: Enter only the host names, with ports where needed, for example mongo-1.internal:27017,mongo-2.internal:27017. Put the user and password in User and Password, and the database in Location.

An SRV Host Is Refused

The test fails with "An SRV (mongodb+srv) host is a single hostname without a port."

Cause: DNS Seed List (SRV) is set to Yes (mongodb+srv, e.g. Atlas), and Host holds a port or a list of hosts.

Resolution: With SRV, enter the cluster's single address only, for example cluster0.abcde.mongodb.net. To connect to a list of hosts instead, set DNS Seed List (SRV) to No.

The Test Asks for a User or a Password

The test fails with "Set the username for the MongoDB password." or "Set the password for MongoDB user '...'."

Cause: Only one of User and Password is filled in.

Resolution: Fill in both to sign in, or leave both empty for a server without access control. See Authentication.

The Port Is Refused

The test fails with "Invalid MongoDB port '...'."

Cause: Port is not a whole number between 1 and 65535.

Resolution: Enter the port the server listens on, or leave the field empty for 27017.

Reaching the Servers

The Connection Test Times Out or Reports the Server as Unreachable

Test connection fails without any message about signing in. Qualytics did not get an answer from MongoDB.

Cause: The host or port is wrong, the server is not running, or the network between your Qualytics deployment and MongoDB blocks the connection. On Atlas, the most common cause is an IP access list that does not include the Qualytics addresses.

Resolution: Confirm Host and Port. Then allow the Public addresses or Private addresses shown in the Add Datastore form through your firewall rules or the Atlas IP access list. See Network access.

An Atlas Address Does Not Connect

The test fails for a cluster address of the form cluster0.abcde.mongodb.net.

Cause: DNS Seed List (SRV) is set to No. An Atlas cluster address is a DNS seed list, not a server, so it only works with SRV.

Resolution: Set DNS Seed List (SRV) to Yes (mongodb+srv, e.g. Atlas) and leave Port empty.

The First Host Answers, but the Connection Still Fails

The test fails for a replica set even though the host you entered is reachable.

Cause: The replica set reports its members under names your Qualytics deployment cannot resolve or reach, often internal names that only exist inside your network.

Resolution: Make every member name in the replica set configuration resolvable and reachable from your Qualytics deployment. See Hostname resolution.

The Connection Fails When SSL Connection Is On

Cause: The server does not accept TLS, or its certificate is not one your Qualytics deployment trusts, such as a certificate signed by your own certificate authority.

Resolution: Turn SSL Connection off for a server that does not use TLS. For a server with a certificate from a private authority, ask your Qualytics administrator whether the deployment trusts that authority; the form has no field to upload one.

Signing In

Authentication Fails with Credentials You Know Are Correct

The test reports that authentication failed.

Cause: Most often, Auth Source does not name the database the user was created in. MongoDB rejects the sign-in in the same way whether the password or the Auth Source is wrong.

Resolution: Set Auth Source to the user's database. It is admin for Atlas database users and for most self-hosted users. See The user and the Auth Source.

The Database Dropdown Is Empty or Lacks a Database

The connection test passes, but the Database dropdown offers nothing, or not the database you expected.

Cause: The user cannot see the database, or the database is one of MongoDB's own admin, config, or local, which are never offered.

Resolution: Grant the user the read role on the databases you want to monitor, then test again. See Permissions.

Reading Collections

A Collection Is Missing After the Sync

Cause: The collection is a view, or its name starts with system.. Neither is listed.

Resolution: Point checks at the collection the view reads from, or create a computed table in Qualytics that applies the same logic.

A New Field Does Not Appear

Documents now hold a field that the container does not list.

Cause: A collection's fields are worked out at Sync and kept until the next one.

Resolution: Run a Sync. A rarely used field can still be missed if it is not in any of the sampled documents. See How fields are worked out.

A Field Shows More Empty Values Than Expected

Cause: Some documents store that field with a different type from the one the sample settled on, for example text in a number field, and the value cannot be converted. Those values read as empty.

Resolution: Check the documents for mixed types in that field. Fixing the type at the source is the lasting fix. A Not Null check on the field reports the affected documents as anomalies.

Limitations

  • MongoDB datastores are read-only. Qualytics never writes to MongoDB, and a MongoDB datastore cannot be an enrichment datastore.
  • Views and system. collections are not read.
  • The connection signs in with a user and password only. X.509 certificates, LDAP, Kerberos, and AWS IAM sign-in are not supported.
  • There is no connection string field and no field for extra MongoDB connection options.
  • The form has no field for a custom certificate authority or a client certificate.
  • Fields are worked out from a sample of up to 10,000 documents per collection, so a field that appears in none of the sampled documents is not listed.