mongodb/node-mongodb-native · error · MongoRuntimeError

Namespace cannot contain a null character

Error message

Namespace cannot contain a null character

What it means

Thrown as a MongoRuntimeError in the OpQueryRequest constructor when the constructed namespace (databaseName + '.$cmd') contains a NUL byte (\x00). In the MongoDB wire protocol the collection name is a C-string terminated by NUL, so an embedded NUL would silently truncate the namespace and route the command to the wrong collection. This guard rejects such input early.

Solutions

1. Sanitize database and collection names to reject control characters (especially \x00) before use
2. Trace where the NUL byte entered the namespace string (e.g. a buffer read without trimming)
3. Validate user-supplied collection/db names against /^[A-Za-z0-9_.-]+$/

Example fix

// before
const db = client.db(nameFromFile); // nameFromFile may contain a NUL byte

// after
if (/\x00/.test(nameFromFile)) throw new Error('Invalid db name');
const db = client.db(nameFromFile);

function assertSafeNamespace(name: string) {
  if (name.indexOf('\x00') !== -1) throw new Error(`Namespace contains NUL: ${JSON.stringify(name)}`);
}
assertSafeNamespace(dbName);
assertSafeNamespace(collectionName);

function isNulFreeNamespace(name: string): boolean {
  return !name.includes('\x00');
}

When it happens

Trigger: The database name passed to OpQueryRequest contains a literal \x00 character. Because the driver normally derives databaseName from the user's db/collection strings, this means a NUL byte appeared in a database or collection name in the user's code.

Common situations: Reading a database/collection name from untrusted input that includes a NUL byte; binary data accidentally concatenated into a namespace; a logging or injection test that injects control characters.

Related errors

• Argument "size" must be a non-negative number
• Auth mechanism property ALLOWED_HOSTS is not allowed in the…
• Cannot parse namespace from
• Database names cannot contain the character '.'
• Raw operations are not allowed

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

Appendix: source

Thrown at src/cmap/commands.ts:103

  /** 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;
    this.returnFieldSelector = options.returnFieldSelector || undefined;
    this.requestId = options.requestId ?? OpQueryRequest.getRequestId();

    // special case for pre-3.2 find commands, delete ASAP
    this.pre32Limit = options.pre32Limit;

    // Serialization option
    this.serializeFunctions =

View on GitHub (pinned to dce7939f86)