What causes "A collection name must be determined before killCursors" in mongodb/node-mongodb-native?

Prefer collection-scoped operations so cursors always carry a collection name.

mongodb/node-mongodb-native · error · MongoRuntimeError

A collection name must be determined before killCursors

Error message

A collection name must be determined before killCursors

What it means

Thrown by KillCursorsOperation.buildCommand when this.ns.collection is null/undefined, so the killCursors command has no collection to target. The driver sends killCursors to clean up server-side cursors when iteration stops early; if the cursor's namespace lacks a collection name, cleanup cannot proceed. It is a MongoRuntimeError and, per spec, killCursors errors are otherwise swallowed by handleError - this particular throw happens during command construction, before that suppression.

Source

Thrown at src/operations/kill_cursors.ts:41

  cursorId: Long;

  constructor(cursorId: Long, ns: MongoDBNamespace, server: Server, options: OperationOptions) {
    super(options);
    this.ns = ns;
    this.cursorId = cursorId;
    this.server = server;
  }

  override get commandName() {
    return 'killCursors' as const;
  }

  override buildCommand(_connection: Connection, _session?: ClientSession): KillCursorsCommand {
    const killCursors = this.ns.collection;
    if (killCursors == null) {
      // Cursors should have adopted the namespace returned by MongoDB
      // which should always defined a collection name (even a pseudo one, ex. db.aggregate())
      throw new MongoRuntimeError('A collection name must be determined before killCursors');
    }

    const killCursorsCommand: KillCursorsCommand = {
      killCursors,
      cursors: [this.cursorId]
    };

    return killCursorsCommand;
  }

  override buildOptions(timeoutContext: TimeoutContext): ServerCommandOptions {
    return {
      session: this.session,
      timeoutContext
    };
  }

  override handleError(_error: MongoError): void {

View on GitHub (pinned to 3366c21a63)

Solutions

Prefer collection-scoped operations so cursors always carry a collection name.
Let cursors exhaust naturally where possible to avoid the killCursors path.
If standard operations reproduce this, report it as a driver bug with topology and version details.
Avoid manually closing or constructing cursors outside the public API.

Defensive patterns

Strategy: try-catch

Try / catch

try {
  await cursor.close();
} catch (e) {
  // killCursors errors are usually safe to ignore; a 'collection name' runtime error
  // indicates a namespace gap - log and continue rather than aborting cleanup.
  if (!(e instanceof MongoRuntimeError && /collection name/.test(e.message))) throw e;
}

Prevention

Let cursors exhaust naturally where possible to avoid the killCursors path.
Use collection-scoped operations so the namespace is always complete.
Don't construct cursors outside the public API.

When it happens

Trigger: A cursor with an incomplete namespace being closed/killed (e.g., breaking out of a for-await loop early on a database-level aggregation cursor, triggering automatic killCursors on cleanup). Same namespace-adoption gap as the getMore variant, but on the teardown path.

Common situations: Early-break from iterating db.aggregate()/change-stream cursors; driver version mismatch in namespace handling; internal/custom cursor construction.

Related errors

AI-assisted analysis of mongodb/node-mongodb-native@3366c21a63 (2026-08-04). Data as JSON: /data/errors/a07a732138c0f335.json. Report an issue: GitHub.