Help
MongoDB and FerretDB errors and how to fix them
Tested with:Databasezy API v1 · zb CLI 0.1
FerretDB is available on every plan, including Free. MongoDB (Percona Server) is available on paid plans only. Both
speak the MongoDB wire protocol through the same gateway. You connect with any MongoDB driver as user app, with
tls=true, authSource=admin and authMechanism=SCRAM-SHA-256. The gateway answers errors in MongoDB’s own format,
with a MongoDB error code.
Server selection timed out or ReplicaSetNoPrimary (MongoDB)
Section titled “Server selection timed out or ReplicaSetNoPrimary (MongoDB)”Cause: the connection string is missing directConnection=true. Each MongoDB instance is a single-member replica
set. Without that option, the driver tries to reach the member by its internal address, which is not reachable from
outside.
Fix: add directConnection=true. Do not use mongodb+srv://. Connect to the host and port from the Connect
tab. See MongoDB connection details.
If the same string works in mongosh, that does not prove it is complete. mongosh connects directly by default when a
string names one host and no replicaSet, but drivers do not.
The connection closes right away, or the TLS handshake fails
Section titled “The connection closes right away, or the TLS handshake fails”Cause: in these cases the gateway closes the connection without a MongoDB reply:
- the driver did not use TLS (
tls=trueis missing) - you connected by IP address, so no TLS server name was sent
- your address is not on the allow-list
- your address is temporarily blocked: by default, 10 failed logins from one address within a minute block it for 10 minutes
Fix: use tls=true and the exact host name, and add your egress CIDR under Network → IP allow-list. Pass the CA
bundle only if your driver does not read the system trust store. See Connect to FerretDB and
IP allow-lists.
Authentication failed (code 18)
Section titled “Authentication failed (code 18)”Cause: wrong password, the wrong authSource, or a rotated credential. The user app is defined in the admin
authentication database. After a rotation there is no overlap: the old password stops working once the new one is
applied.
Fix: set authSource=admin and reveal the current password with zb instances credentials reveal <instance_id>.
See Rotating credentials.
not authorized on <database> to execute command (MongoDB)
Section titled “not authorized on <database> to execute command (MongoDB)”Cause: app has the readWrite and dbOwner roles on the app database only. It cannot use other databases or
run cluster commands such as replSetGetStatus.
Fix: keep your collections in the app database. Extra users are not available.
createUser fails (FerretDB)
Section titled “createUser fails (FerretDB)”Cause: FerretDB cannot create users on Databasezy, because app has no right to create roles.
Fix: have every client connect as app. Each FerretDB instance has one logical database.
An error on a command, operator or stage that works on MongoDB (FerretDB)
Section titled “An error on a command, operator or stage that works on MongoDB (FerretDB)”Cause: FerretDB does not implement every MongoDB feature. The usual gaps are:
- change streams
$textsearch- GridFS
- multi-document transactions
Fix: if your application needs these, use the MongoDB (Percona Server) engine. Moving between the two engines is an
instance-to-instance migration with zb migrate. Run your test suite against a FerretDB instance before you move
production. See FerretDB.
Error code 13 Unauthorized: “too many connections for this instance”
Section titled “Error code 13 Unauthorized: “too many connections for this instance””Cause: the instance already has as many connections as its size allows. On FerretDB, each MongoDB connection is
also a PostgreSQL connection underneath. A similar error, connection rate limit exceeded; slow down, means clients
opened more than 50 new connections in one second.
Fix: set maxPoolSize well below the size’s connection limit, divided across your services. Use one client per
process. See Too many connections.
Error code 91 ShutdownInProgress: paused or waking up
Section titled “Error code 91 ShutdownInProgress: paused or waking up”Cause: the message tells you which:
paused: the instance is paused by its owner; resume it in the portal or with `zb instances resume`. Someone paused the instance; connections never wake it. Runzb instances resume <instance_id>.paused: the instance was paused by Databasezy support; contact support to resume it. Only support can resume it.the instance is waking up; retry in a few seconds. A paused instance did not wake within the gateway’s 30-second hold. Retry. Free FerretDB instances pause after 15 minutes without connections.
Fix: see Paused and waking instances. A suspended: ... or
quota_exceeded: ... message means billing or a quota stopped the instance. See
Spending caps and quota errors.
Error code 6 HostUnreachable: “instance unavailable; retry in a few seconds”
Section titled “Error code 6 HostUnreachable: “instance unavailable; retry in a few seconds””Cause: the gateway could not reach the database, for example during a restart.
Fix: retry. If it lasts more than a few minutes, check the instance status with zb instances get <instance_id>,
then open a ticket.
No replicas, failover or point-in-time recovery on MongoDB
Section titled “No replicas, failover or point-in-time recovery on MongoDB”These are not built yet. A MongoDB instance has one member, and its backups are mongodump snapshots without
point-in-time recovery. FerretDB stores its data in PostgreSQL, so its backups come from the PostgreSQL side. See
Backups and restore.
Still stuck?
Section titled “Still stuck?”Search the help center or ask the assistant in the portal Help panel. If that does not solve it, open a support ticket from the portal (Help → Open a ticket) and include:
- the instance id, engine (MongoDB or FerretDB) and region
- the exact error text and code
- your driver and its version
- your connection options, with the password removed
- the time of the failure in UTC
Never paste passwords, connection strings with passwords, API keys or patient data (PHI) into a ticket. See How to get help.