mongodb/node-mongodb-native · warning · 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 as a MongoRuntimeError in the OpQueryRequest constructor when databaseName is not typeof string. OpQueryRequest is the legacy OP_QUERY wire protocol message (pre-MongoDB 3.2), used internally for some monitoring/handshake paths. This is a defensive internal invariant check — the public API always supplies a string.

Solutions

1. Report a driver bug with the stack trace — databaseName should always be a string internally
2. If testing with mocks, ensure the databaseName argument is a string
3. Avoid constructing OpQueryRequest directly; it is marked @internal

function isStringDbName(name: unknown): name is string {
  return typeof name === 'string';
}

When it happens

Trigger: Internal driver code constructs an OpQueryRequest with a non-string databaseName. Effectively unreachable from user code; would indicate a bug in driver internals or a faulty mock in tests.

Common situations: Driver bug, an incorrectly written test mock that passes a non-string, or a fork that calls the internal constructor directly with bad data.

Related errors

• A query document must be specified for query
• Argument "size" must be a non-negative number
• Query document must be specified for query
• A collection name must be determined before getMore
• A collection name must be determined before killCursors

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

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