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 as a MongoRuntimeError by KillCursorsOperation.buildCommand when the cursor's namespace has no collection name (this.ns.collection == null). killCursors must name a collection, and a null collection indicates the cursor namespace was not set, which is an internal-state problem rather than user input.

Solutions

1. Use standard collection-scoped APIs to create cursors so the namespace is populated.
2. Report persistent reproductions to the driver maintainers as an internal defect.
3. Do not manually construct KillCursorsOperation with incomplete namespaces in tests.

try {
  await cursor.close();
} catch (err) {
  if (err instanceof MongoRuntimeError && /collection name must be determined before killCursors/.test(err.message)) {
    // cleanup of a namespace-deficient cursor; ignore, the cursor is local-only
  } else throw err;
}

When it happens

Trigger: The driver attempts to clean up (kill) a cursor whose namespace.collection is null/undefined. Typically arises during cursor cleanup for collection-less or namespace-deficient cursors, or from internal/test construction of cursors.

Common situations: Driver-internal cleanup paths; test harnesses that build cursors without full namespaces; edge cases with db-level operations.

Related errors

• A collection name must be determined before getMore
• An unexpected error type
• Unable to iterate cursor with no id
• A query document must be specified for query
• Argument for maxTimeMS must be a number

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

Appendix: 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 dce7939f86)