mongodb/node-mongodb-native · error · MongoRuntimeError

Cannot parse namespace from

Error message

Cannot parse namespace from "${namespace}"

What it means

Thrown by MongoDBNamespace.fromString() when the namespace argument is not a string or is an empty string. The parser splits on '.' to extract db and collection; an empty or non-string input has no valid db component. The TODO comment notes this should eventually be a MongoNamespaceError but currently raises MongoRuntimeError.

Solutions

1. Ensure any namespace string passed contains at least a non-empty database name.
2. Validate db and collection names are non-empty strings before constructing namespace-dependent operations.
3. Check environment variables or config that feed into db/collection names.

Example fix

// before
const dbName = process.env.DB_NAME; // undefined
client.db(dbName).collection('items');

// after
const dbName = process.env.DB_NAME || 'default_db';
client.db(dbName).collection('items');

function requireNamespace(ns: string | undefined): string {
  if (typeof ns !== 'string' || ns.trim() === '') throw new Error('Namespace must be a non-empty string');
  return ns;
}

function isNonEmptyString(v: unknown): v is string {
  return typeof v === 'string' && v.length > 0;
}

try {
  const ns = MongoDBNamespace.fromString(input);
} catch (e) {
  if (e instanceof MongoRuntimeError && /Cannot parse namespace/.test(e.message)) {
    // fall back to a safe default namespace
  } else throw e;
}

When it happens

Trigger: Internal calls that build a namespace from an empty or undefined string, e.g. when a collection name is computed dynamically and resolves to ''. Rarely user-facing unless the namespace is passed through a public API that accepts arbitrary strings.

Common situations: Dynamic code that derives db or collection names from variables that may be undefined/empty. Using client.db('') or db.collection('') in some internal paths. Misconfigured environment variables for database/collection names.

Related errors

• Auth mechanism property ALLOWED_HOSTS must be an array of…
• Cannot create a Timeout with a negative duration
• Currently only a ENVIRONMENT in
• Database names cannot contain the character '.'
• Invalid CANONICALIZE_HOST_NAME value

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

Appendix: source

Thrown at src/utils.ts:278

   * @param collection - collection name
   */
  constructor(db: string, collection?: string) {
    this.db = db;
    this.collection = collection === '' ? undefined : collection;
  }

  toString(): string {
    return this.collection ? `${this.db}.${this.collection}` : this.db;
  }

  withCollection(collection: string): MongoDBCollectionNamespace {
    return new MongoDBCollectionNamespace(this.db, collection);
  }

  static fromString(namespace?: string): MongoDBNamespace {
    if (typeof namespace !== 'string' || namespace === '') {
      // TODO(NODE-3483): Replace with MongoNamespaceError
      throw new MongoRuntimeError(`Cannot parse namespace from "${namespace}"`);
    }

    const [db, ...collectionParts] = namespace.split('.');
    const collection = collectionParts.join('.');
    return new MongoDBNamespace(db, collection === '' ? undefined : collection);
  }
}

/**
 * @public
 *
 * A class representing a collection's namespace.  This class enforces (through Typescript) that
 * the `collection` portion of the namespace is defined and should only be
 * used in scenarios where this can be guaranteed.
 */
export class MongoDBCollectionNamespace extends MongoDBNamespace {
  override collection: string;

View on GitHub (pinned to dce7939f86)