Automattic/mongoose · error · MongooseError

Cannot call `setClient()` with a MongoClient that you have n

Error message

Cannot call `setClient()` with a MongoClient that you have not called `connect()` on yet.

What it means

setClient() requires an already-connected MongoClient: it checks client.topology != null, which is only set after await client.connect() succeeds. Passing a freshly constructed, unconnected client throws this MongooseError because Mongoose would otherwise serve queries against a client with no server topology.

Source

Thrown at lib/drivers/node-mongodb-native/connection.js:418

  return {
    schemaMap, encryptedFieldsMap
  };
};

/*!
 * ignore
 */

NativeConnection.prototype.setClient = function setClient(client) {
  if (!(client instanceof mongodb.MongoClient)) {
    throw new MongooseError('Must call `setClient()` with an instance of MongoClient');
  }
  if (this.readyState !== STATES.disconnected) {
    throw new MongooseError('Cannot call `setClient()` on a connection that is already connected.');
  }
  if (client.topology == null) {
    throw new MongooseError('Cannot call `setClient()` with a MongoClient that you have not called `connect()` on yet.');
  }

  this._connectionString = client.s.url;
  _setClient(this, client, {}, client.s.options.dbName);

  for (const model of Object.values(this.models)) {
    // Errors handled internally, so safe to ignore error
    model.init().catch(function $modelInitNoop() {});
  }

  return this;
};

/*!
 * ignore
 */

function _setClient(conn, client, options, dbName) {

View on GitHub (pinned to 49cdab0136)

Solutions

1. Connect the client first: await client.connect(); then await conn.setClient(client).
2. Or skip manual client management: await conn.openUri(uri) / mongoose.connect(uri) handles connect internally.

Example fix

// before
const client = new MongoClient(uri);
conn.setClient(client); // throws: topology is null

// after
const client = new MongoClient(uri);
await client.connect();
await conn.setClient(client);

if (client.topology == null) {
  await client.connect();
}
await conn.setClient(client);

function isClientConnected(client) {
  return client.topology != null;
}

When it happens

Trigger: const client = new MongoClient(uri); conn.setClient(client); without await client.connect(); - also when connect() was started but not awaited, leaving topology null at call time.

Common situations: Copy-pasting driver examples that stop at new MongoClient(uri); assuming Mongoose performs the connect for you; a forgotten await on client.connect().

Related errors

• Must call `setClient()` with an instance of MongoClient
• Cannot set a document's session to a session that has ended.
• Can't call `openUri()` on an active connection with differen
• Cannot call `setClient()` on a connection that is already co
• Arguments must be aggregate pipeline operators

AI-assisted analysis of Automattic/mongoose@49cdab0136 (2026-08-21). Data as JSON: /api/errors/113eaa3468c30e3c. Report an issue: GitHub.