mongodb/node-mongodb-native · error · MongoInvalidArgumentError

Database names cannot contain the character '.'

Error message

Database names cannot contain the character '.'

What it means

The Db constructor validates that the database name does not contain a dot because dots are MongoDB namespace separators (db.collection). A dot in a db name would corrupt namespace parsing, routing, and command construction.

Source

Thrown at src/db.ts:159

  /**
   * Creates a new Db instance.
   *
   * Db name cannot contain a dot, the server may apply more restrictions when an operation is run.
   *
   * @param client - The MongoClient for the database.
   * @param databaseName - The name of the database this instance represents.
   * @param options - Optional settings for Db construction.
   */
  constructor(client: MongoClient, databaseName: string, options?: DbOptions) {
    options = options ?? {};

    // Filter the options
    options = filterOptions(options, DB_OPTIONS_ALLOW_LIST);

    // Ensure there are no dots in database name
    if (typeof databaseName === 'string' && databaseName.includes('.')) {
      throw new MongoInvalidArgumentError(`Database names cannot contain the character '.'`);
    }

    // Internal state of the db object
    this.s = {
      // Options
      options,
      // Unpack read preference
      readPreference: ReadPreference.fromOptions(options),
      // Merge bson options
      bsonOptions: resolveBSONOptions(options, client),
      // Set up the primary key factory or fallback to ObjectId
      pkFactory: options?.pkFactory ?? DEFAULT_PK_FACTORY,
      // ReadConcern
      readConcern: ReadConcern.fromOptions(options),
      writeConcern: WriteConcern.fromOptions(options),
      // Namespace
      namespace: new MongoDBNamespace(databaseName)
    };

View on GitHub (pinned to 3366c21a63)

Solutions

1. Replace dots in the name with dashes or underscores (e.g. 'tenant_app')
2. If the dot was meant to separate db from collection, pass only the db portion to client.db()
3. Sanitize external/user input before passing it to client.db()

Example fix

// before
const db = client.db('tenant.app');
// after
const db = client.db('tenant_app');

function safeDbName(name: string): string {
  if (typeof name === 'string' && name.includes('.')) {
    throw new Error(`Invalid db name '${name}': dots are not allowed`);
  }
  return name;
}
const db = client.db(safeDbName(input));

function isValidDbName(name: unknown): name is string {
  return typeof name === 'string' && name.length > 0 && !name.includes('.');
}

When it happens

Trigger: client.db('my.app'), new Db(client, 'tenant.prod'), or any path that constructs a Db with a dotted name.

Common situations: Multi-tenant names using dots; passing a full 'db.collection' namespace to client.db(); mis-decoded connection-string dbName.

Related errors

• Namespace cannot contain a null character
• Cannot parse namespace from "${namespace}"
• Update document requires atomic operators
• Replacement document must not use atomic operators
• Bulk find operation must specify a selector

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