What causes "listDatabases() not implemented by driver" in Automattic/mongoose?

Use a standard connection: const conn = await mongoose.createConnection(uri).asPromise()

Automattic/mongoose · error · MongooseError

listDatabases() not implemented by driver

Error message

listDatabases() not implemented by driver

What it means

The base Connection class only declares listDatabases(); the real implementation lives in the bundled node-mongodb-native driver (lib/drivers/node-mongodb-native/connection.js:222, which delegates to this.db.admin().listDatabases()). Seeing this error means the connection object is not backed by the native driver — a custom Connection subclass or test double that never overrode the method.

Source

Thrown at lib/connection.js:919

};

/**
 * Helper for MongoDB Node driver's `listDatabases()`.
 * Returns an object with a `databases` property that contains an
 * array of database objects.
 *
 * #### Example:
 *     const { databases } = await mongoose.connection.listDatabases();
 *     databases; // [{ name: 'mongoose_test', sizeOnDisk: 0, empty: false }]
 *
 * @method listCollections
 * @return {Promise<Array<{ databases: { name: string } }>>}
 * @api public
 */

Connection.prototype.listDatabases = async function listDatabases() {
  // Implemented in `lib/drivers/node-mongodb-native/connection.js`
  throw new MongooseError('listDatabases() not implemented by driver');
};

/**
 * Helper for `dropDatabase()`. Deletes the given database, including all
 * collections, documents, and indexes.
 *
 * #### Example:
 *
 *     const conn = mongoose.createConnection('mongodb://127.0.0.1:27017/mydb');
 *     // Deletes the entire 'mydb' database
 *     await conn.dropDatabase();
 *
 * @method dropDatabase
 * @return {Promise}
 * @api public
 */

Connection.prototype.dropDatabase = async function dropDatabase() {

View on GitHub (pinned to 49cdab0136)

Solutions

Use a standard connection: const conn = await mongoose.createConnection(uri).asPromise()
Bypass the Mongoose sugar and call the driver directly: const { databases } = await conn.db.admin().listDatabases()
If you maintain a custom connection class, implement listDatabases() on it

Example fix

// before
const conn = new CustomConnection(); // subclass lacking listDatabases
await conn.listDatabases(); // throws

// after
const conn = await mongoose.createConnection(uri).asPromise();
const { databases } = await conn.listDatabases();

Defensive patterns

Strategy: try-catch

Try / catch

let databases;
try {
  ({ databases } = await conn.listDatabases());
} catch (err) {
  if (/not implemented by driver/.test(err.message)) {
    ({ databases } = await conn.db.admin().listDatabases());
  } else {
    throw err;
  }
}

Prevention

Create connections only through mongoose.connect()/mongoose.createConnection()
For custom driver classes, implement every documented Connection method
When unsure a custom connection supports the sugar, call the driver directly: conn.db.admin().listDatabases()

When it happens

Trigger: Calling conn.listDatabases() on a custom Connection subclass, mock, or bare base Connection instance whose class does not override listDatabases().

Common situations: Writing unit-test fakes/stubs for Connection; building alternate driver adapters; rarely, instantiating the base Connection directly instead of using mongoose.createConnection().

Related errors

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