Skip to content

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=true is 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.

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.

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
  • $text search
  • 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. Run zb 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.

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.