mongodb/node-mongodb-native · error · MongoRuntimeError

Database name must be a string for a query

Error message

Database name must be a string for a query

What it means

Thrown by the OpQueryRequest constructor (commands.ts:95) as a MongoRuntimeError when databaseName is not a string. OP_QUERY is the legacy wire protocol message; the database name is required to build the namespace ('db.$cmd'). A non-string value indicates an internal caller passed invalid arguments - this is an internal invariant, not user-reachable through the public API.

Source

Thrown at src/cmap/commands.ts:95

  batchSize: number;
  tailable: boolean;
  secondaryOk: boolean;
  oplogReplay: boolean;
  noCursorTimeout: boolean;
  awaitData: boolean;
  exhaust: boolean;
  partial: boolean;
  /** moreToCome is an OP_MSG only concept */
  moreToCome = false;
  databaseName: string;
  query: Document;

  constructor(databaseName: string, query: Document, options: OpQueryOptions) {
    // Basic options needed to be passed in
    // TODO(NODE-3483): Replace with MongoCommandError
    const ns = `${databaseName}.$cmd`;
    if (typeof databaseName !== 'string') {
      throw new MongoRuntimeError('Database name must be a string for a query');
    }
    // TODO(NODE-3483): Replace with MongoCommandError
    if (query == null) throw new MongoRuntimeError('A query document must be specified for query');

    // Validate that we are not passing 0x00 in the collection name
    if (ns.indexOf('\x00') !== -1) {
      // TODO(NODE-3483): Use MongoNamespace static method
      throw new MongoRuntimeError('Namespace cannot contain a null character');
    }

    // Basic optionsa
    this.databaseName = databaseName;
    this.query = query;
    this.ns = ns;

    // Additional options
    this.numberToSkip = options.numberToSkip || 0;
    this.numberToReturn = options.numberToReturn || 0;

View on GitHub (pinned to 3366c21a63)

Solutions

1. Report as a driver bug - include the operation that triggered it and the driver version
2. Avoid constructing OpQueryRequest directly - use the high-level collection/db APIs
3. If subclassing, ensure databaseName is always a string before calling super()

try {
  await client.connect();
} catch (e) {
  if (e instanceof MongoRuntimeError && /Database name must be a string/i.test(e.message)) {
    // internal bug - report with operation + driver version
  }
  throw e;
}

When it happens

Trigger: Internal code constructing new OpQueryRequest(undefined, query, options) or passing a number/object as databaseName. Reachable only via driver internals or subclasses that bypass type checks.

Common situations: Driver bug where a namespace resolution returned undefined; custom wire-protocol extension code misusing the OpQueryRequest constructor.

Related errors

• A query document must be specified for query
• Namespace cannot contain a null character
• Query document must be specified for query
• Argument "size" must be a non-negative number
• Operation passed in cannot be an Array

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