{"record":{"id":"2df07b3b111892eb","repo":"mongodb/node-mongodb-native","slug":"database-names-cannot-contain-the-character","errorCode":null,"errorMessage":"Database names cannot contain the character '.'","messagePattern":"Database names cannot contain the character '\\.'","errorType":"exception","errorClass":"MongoInvalidArgumentError","httpStatus":null,"severity":"error","filePath":"src/db.ts","lineNumber":159,"sourceCode":"\n  /**\n   * Creates a new Db instance.\n   *\n   * Db name cannot contain a dot, the server may apply more restrictions when an operation is run.\n   *\n   * @param client - The MongoClient for the database.\n   * @param databaseName - The name of the database this instance represents.\n   * @param options - Optional settings for Db construction.\n   */\n  constructor(client: MongoClient, databaseName: string, options?: DbOptions) {\n    options = options ?? {};\n\n    // Filter the options\n    options = filterOptions(options, DB_OPTIONS_ALLOW_LIST);\n\n    // Ensure there are no dots in database name\n    if (typeof databaseName === 'string' && databaseName.includes('.')) {\n      throw new MongoInvalidArgumentError(`Database names cannot contain the character '.'`);\n    }\n\n    // Internal state of the db object\n    this.s = {\n      // Options\n      options,\n      // Unpack read preference\n      readPreference: ReadPreference.fromOptions(options),\n      // Merge bson options\n      bsonOptions: resolveBSONOptions(options, client),\n      // Set up the primary key factory or fallback to ObjectId\n      pkFactory: options?.pkFactory ?? DEFAULT_PK_FACTORY,\n      // ReadConcern\n      readConcern: ReadConcern.fromOptions(options),\n      writeConcern: WriteConcern.fromOptions(options),\n      // Namespace\n      namespace: new MongoDBNamespace(databaseName)\n    };","sourceCodeStart":141,"sourceCodeEnd":177,"githubUrl":"https://github.com/mongodb/node-mongodb-native/blob/dce7939f86fb283e167ad709955abedb7bf23124/src/db.ts#L141-L177","documentation":"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.","triggerScenarios":"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().","commonSituations":"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.","solutions":["Remove dots from the database name; use underscores or hyphens instead (e.g. 'app_production').","If you intended to reference a collection, split the namespace: client.db('app').collection('production').","Sanitize/validate any dynamic database name derived from user or env input before passing it to db()."],"exampleFix":"// before\nconst db = client.db(`${tenant}.${env}`);\n// after\nconst db = client.db(`${tenant}_${env}`);","handlingStrategy":"validation","validationCode":"function validDbName(name) {\n  return typeof name === 'string' && name.length > 0 && !name.includes('.');\n}\n// before constructing:\nif (!validDbName(dbName)) throw new Error(`Invalid db name: ${dbName}`);\nconst db = client.db(dbName);","typeGuard":"function isValidDbName(name: unknown): name is string {\n  return typeof name === 'string' && name.length > 0 && !name.includes('.');\n}","tryCatchPattern":"try {\n  const db = client.db(name);\n} catch (e) {\n  if (e instanceof MongoInvalidArgumentError && /Database names/.test(e.message)) {\n    // handle invalid db name\n  }\n  throw e;\n}","preventionTips":["Never build db names by concatenating untrusted segments with '.'.","Centralize db-name creation in one helper that strips/replaces dots.","Add a unit test that asserts your db-name source never contains '.'."],"tags":["validation","namespace","synchronous"],"backgroundTag":null,"analyzedSha":"dce7939f86fb283e167ad709955abedb7bf23124","analyzedAt":"2026-08-11T04:54:53.215Z","contentChangedAt":null,"schemaVersion":2},"datasetVersion":"2026-09-23T08:17:48.524Z"}