Connection problems
The errors people actually hit when a connection will not open: server version, TLS, SRV lookups, Atlas IP access, and SSH tunnels.
Monghoul tests connectivity and credentials before saving a profile, so most problems show up at that point rather than on your first query.
The server is older than 4.4
Monghoul requires MongoDB 4.4 or newer and refuses an older server with an explicit error rather than connecting and failing in unclear ways later.
There is no workaround inside the app. Upgrade the server, or use a different client for that instance.
Authentication fails but the credentials are right
Check the authentication source. It is a separate setting from the username and password, and it
is the database the credentials are defined in, which is very often admin rather than the database
you are trying to read.
If you connected from a URI, the source came from the URI’s authSource parameter. Paste the URI
into the connection string parser to see what it actually says.
An Atlas cluster times out
Two usual causes, in this order:
- IP access list. Atlas rejects connections from addresses that are not on the project’s access list, and it does that before authentication, so it looks like a timeout rather than an auth error. Add your address in the Atlas UI.
- SRV lookup. A
mongodb+srv://string needs a DNS SRV record resolved before anything connects. On a network that filters DNS, or behind some VPNs, that lookup fails. Try the non-SRVmongodb://form with the hosts listed explicitly.
TLS fails against a self-signed certificate
Give the connection the CA certificate file. That is the correct fix, and it keeps verification on.
The dialog also has an option to allow invalid certificates. It exists for self-signed development setups, and it should not be used against anything that matters, because it turns off the check that makes TLS worth having.
The SSH tunnel opens and then drops
Tunnels close when their connection, or a connection test, ends. A tunnel that goes away when you disconnect is working as intended.
If it drops while the connection is still up, the usual cause is a server that closes idle sessions, and reconnecting the profile rebuilds it. A tunnel that never came up is different: it reports its own reason and the connection does not open at all, so you are not left guessing which half worked.
The connection is marked offline in the sidebar
A disconnected connection is dimmed in the tree. Reconnect it from its context menu, which reports the underlying error if it fails again.
A saved password stopped working after copying a profile between machines
Stored secrets are encrypted on the device that saved them. A profile copied to another machine carries a secret that machine cannot decrypt, and Monghoul treats an undecryptable secret as empty.
That is deliberate, and it fails safely: the affected connection can still be edited and deleted, and the other connections are unaffected. Re-enter the password on the new machine.
Nothing above matches
Open the operation log (Logs in the status bar). It records every operation with its outcome, and
the failing one usually carries the server’s own error message.
If that does not resolve it, get in touch with the error text and your server version.