mongodb/node-mongodb-native · error · MongoRuntimeError

Namespace cannot contain a null character

Error message

Namespace cannot contain a null character

What it means

Thrown by the OpQueryRequest constructor (commands.ts:103) as a MongoRuntimeError when the constructed namespace ('databaseName.$cmd') contains a null byte (\x00). Null bytes are the BSON/C string terminator; embedding one would truncate or corrupt the wire message, so the driver rejects it defensively.

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 3366c21a63)

Solutions

1. Sanitize database/collection names: strip or reject control characters including \x00
2. Validate user-supplied namespace input against /^[a-zA-Z0-9_-]+$/ before use
3. If reading names from external data, scrub null bytes: name.replace(/\x00/g, '')

Example fix

// before
const dbName = taintedInput; // may contain \x00
// after
const dbName = taintedInput.replace(/[\x00-\x1f]/g, '');

function sanitizeNamespaceName(name: string): string {
  if (/[\x00]/.test(name)) throw new Error('namespace contains null byte');
  return name;
}
const dbName = sanitizeNamespaceName(userInput);

function isCleanNamespaceName(name: unknown): name is string {
  return typeof name === 'string' && !/\x00/.test(name) && /^[A-Za-z0-9_-]+$/.test(name);
}

When it happens

Trigger: databaseName contains a literal \x00 character (e.g. from corrupted input, unsafe string concatenation, or a binary value coerced to string). The check runs on the composed 'db.$cmd' string.

Common situations: Untrusted input used to form a database name without sanitization; binary data leaking into a namespace string; log/parser code that mishandles buffers. Very rare in practice since database names from the public API go through Db/collection construction with their own validation.

Related errors

• Database name must be a string for a query
• A query document must be specified for query
• Query document must be specified for query
• Database names cannot contain the character '.'
• Cannot parse namespace from "${namespace}"

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