mongodb/node-mongodb-native · error · MongoRuntimeError

Cannot parse namespace from "${namespace}"

Error message

Cannot parse namespace from "${namespace}"

What it means

Thrown by MongoDBNamespace.fromString() (the engine behind the internal ns() helper) when the namespace argument is not a non-empty string. A MongoDB namespace is a 'database' or 'database.collection' pair, so an empty/undefined value cannot be parsed into a valid db+collection. It is raised as a MongoRuntimeError (with a TODO to become MongoNamespaceError) whenever internal code builds a namespace from a bad string. It almost always indicates an empty database or collection name being passed by the caller.

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

Solutions

1. Provide a non-empty database name: ensure process.env.DB_NAME is set and has a fallback (e.g. process.env.DB_NAME || 'app').
2. Validate the collection name is a non-empty string before calling db.collection(name).
3. If constructing namespaces manually, assert the input with a guard that throws a clearer error earlier.

Example fix

// before
const coll = client.db(process.env.DB_NAME).collection(process.env.COLL_NAME);
// DB_NAME unset => '' or undefined => MongoRuntimeError

// after
const dbName = process.env.DB_NAME || 'app';
const collName = process.env.COLL_NAME || 'users';
if (!dbName || !collName) throw new Error('DB and collection names are required');
const coll = client.db(dbName).collection(collName);

function requireNamespace(db: unknown, coll: unknown): { db: string; coll: string } {
  if (typeof db !== 'string' || db === '') throw new Error('db name must be a non-empty string');
  if (typeof coll !== 'string' || coll === '') throw new Error('collection name must be a non-empty string');
  return { db, coll };
}

function isValidNamespace(s: unknown): s is string {
  return typeof s === 'string' && s.length > 0 && /^[^.][^\\ ]*$/.test(s);
}

When it happens

Trigger: Passing an empty string to db.collection(''), calling client.db(''), or building a namespace from an undefined variable (e.g. process.env.DB_NAME when the env var is unset). Also triggered when an aggregation/operation internal path receives an empty namespace string.

Common situations: Missing environment variable for the database name (process.env.MONGODB_DB resolves to undefined); template-string typos producing ''; reading collection name from config that failed to load; dynamic code computing the collection name to undefined.

Related errors

• Missing required option `keyVaultNamespace`
• Invalid CANONICALIZE_HOST_NAME value: ${canonicalization}
• TOKEN_RESOURCE must be set in the auth mechanism properties
• User provided OIDC callbacks must return a valid object with
• TOKEN_RESOURCE must be set in the auth mechanism properties

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