mongodb/node-mongodb-native · error · MongoNotConnectedError

MongoClient must be connected to perform this operation

Error message

MongoClient must be connected to perform this operation

What it means

Thrown by getTopology() when neither the provider (MongoClient/ClientSession/AbstractCursor) nor its .client has a non-falsy topology property. The topology is set during MongoClient.connect(); if it is absent the client was never connected or has been closed. Raised as MongoNotConnectedError.

Solutions

1. Ensure await client.connect() has resolved before issuing operations, or rely on lazy connect (first operation) but avoid reusing handles after close().
2. Do not reuse Db/Collection objects obtained from a MongoClient after calling client.close(); create a new client and reconnect.
3. Check client topology readiness or guard with try/catch around operations that may run before connection.

Example fix

// before
const client = new MongoClient(uri);
const db = client.db('test');
db.collection('c').findOne(); // not connected yet

// after
const client = new MongoClient(uri);
await client.connect();
const db = client.db('test');
await db.collection('c').findOne();

await client.connect();
if (!client.topology) throw new Error('Client failed to connect');
// now safe to run operations

function isClientConnected(client: import('mongodb').MongoClient): boolean {
  return !!client.topology;
}

try {
  await collection.findOne(filter);
} catch (e) {
  if (e instanceof MongoNotConnectedError) {
    await client.connect();
    await collection.findOne(filter);
  } else throw e;
}

When it happens

Trigger: Calling collection.find(), db.command(), or cursor methods before awaiting client.connect() (or before any operation that would auto-connect). Also after client.close() when a stale Db/Collection reference is reused. Or when awaiting client.connect() is skipped because the operation was invoked synchronously at module load.

Common situations: Forgetting to await client.connect() in older driver versions (pre-4.x auto-connect is typical but not guaranteed in all code paths), reusing collection/db handles after client.close(), or referencing a collection before the connect promise resolves.

Related errors

• Client must be connected before running operations
• Server is closed
• Can only make Socks5 connections to TCP hosts
• Cannot abort a stream that has already completed
• Cannot call abort() on a stream twice

AI-assisted analysis of mongodb/node-mongodb-native@dce7939f86 (2026-08-11). Data as JSON: /api/errors/18edb275020cfcc3. Report an issue: GitHub.

Appendix: source

Thrown at src/utils.ts:244

  | AbstractCursor
  | Collection<any>
  | Db;

/**
 * A helper function to get the topology from a given provider. Throws
 * if the topology cannot be found.
 * @throws MongoNotConnectedError
 * @internal
 */
export function getTopology(provider: TopologyProvider): Topology {
  // MongoClient or ClientSession or AbstractCursor
  if ('topology' in provider && provider.topology) {
    return provider.topology;
  } else if ('client' in provider && provider.client.topology) {
    return provider.client.topology;
  }

  throw new MongoNotConnectedError('MongoClient must be connected to perform this operation');
}

/** @internal */
export function ns(ns: string): MongoDBNamespace {
  return MongoDBNamespace.fromString(ns);
}

/** @public */
export class MongoDBNamespace {
  db: string;
  collection?: string;
  /**
   * Create a namespace object
   *
   * @param db - database name
   * @param collection - collection name
   */
  constructor(db: string, collection?: string) {

View on GitHub (pinned to dce7939f86)