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 rejects any database name containing a '.' character. In MongoDB the dot is a namespace separator (database.collection), so embedding one in a database name is ambiguous and disallowed by the driver before any server round-trip. This guard lives in the Db constructor at src/db.ts:158 and throws a MongoInvalidArgumentError synchronously.

Solutions

1. Remove dots from the database name; use underscores or hyphens instead (e.g. 'app_production').
2. If you intended to reference a collection, split the namespace: client.db('app').collection('production').
3. Sanitize/validate any dynamic database name derived from user or env input before passing it to db().

Example fix

// before
const db = client.db(`${tenant}.${env}`);
// after
const db = client.db(`${tenant}_${env}`);

function validDbName(name) {
  return typeof name === 'string' && name.length > 0 && !name.includes('.');
}
// before constructing:
if (!validDbName(dbName)) throw new Error(`Invalid db name: ${dbName}`);
const db = client.db(dbName);

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

try {
  const db = client.db(name);
} catch (e) {
  if (e instanceof MongoInvalidArgumentError && /Database names/.test(e.message)) {
    // handle invalid db name
  }
  throw e;
}

When it happens

Trigger: Calling client.db('app.production'), new MongoClient(uri).db('my.db'), or constructing new Db(client, 'a.b') with a dotted string. Also triggered when a connection string's dbname segment contains a dot, e.g. mongodb://host/my.db, that is then handed to db().

Common situations: Developers concatenate environment-based segments like `${tenant}.${env}` to form a database name. Copying a fully-qualified namespace (db.collection) from a query and passing it where only the db name is expected. Misinterpreting a multi-tenant scheme that uses '.' as a delimiter.

Related errors

• Cannot parse namespace from
• Namespace cannot contain a null character
• Option "autoEncryption" must be specified
• A collection name must be determined before getMore
• A collection name must be determined before killCursors

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

Appendix: 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 dce7939f86)