{"id":"6b3e4a9e37664e52","repo":"mongodb/node-mongodb-native","slug":"cannot-parse-namespace-from-namespace","errorCode":null,"errorMessage":"Cannot parse namespace from \"${namespace}\"","messagePattern":"Cannot parse namespace from \"(.+?)\"","errorType":"exception","errorClass":"MongoRuntimeError","httpStatus":null,"severity":"error","filePath":"src/utils.ts","lineNumber":278,"sourceCode":"   * @param collection - collection name\n   */\n  constructor(db: string, collection?: string) {\n    this.db = db;\n    this.collection = collection === '' ? undefined : collection;\n  }\n\n  toString(): string {\n    return this.collection ? `${this.db}.${this.collection}` : this.db;\n  }\n\n  withCollection(collection: string): MongoDBCollectionNamespace {\n    return new MongoDBCollectionNamespace(this.db, collection);\n  }\n\n  static fromString(namespace?: string): MongoDBNamespace {\n    if (typeof namespace !== 'string' || namespace === '') {\n      // TODO(NODE-3483): Replace with MongoNamespaceError\n      throw new MongoRuntimeError(`Cannot parse namespace from \"${namespace}\"`);\n    }\n\n    const [db, ...collectionParts] = namespace.split('.');\n    const collection = collectionParts.join('.');\n    return new MongoDBNamespace(db, collection === '' ? undefined : collection);\n  }\n}\n\n/**\n * @public\n *\n * A class representing a collection's namespace.  This class enforces (through Typescript) that\n * the `collection` portion of the namespace is defined and should only be\n * used in scenarios where this can be guaranteed.\n */\nexport class MongoDBCollectionNamespace extends MongoDBNamespace {\n  override collection: string;\n","sourceCodeStart":260,"sourceCodeEnd":296,"githubUrl":"https://github.com/mongodb/node-mongodb-native/blob/3366c21a6311e02f1be91da982f9b93d3cce99a0/src/utils.ts#L260-L296","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","solutions":["Provide a non-empty database name: ensure process.env.DB_NAME is set and has a fallback (e.g. process.env.DB_NAME || 'app').","Validate the collection name is a non-empty string before calling db.collection(name).","If constructing namespaces manually, assert the input with a guard that throws a clearer error earlier."],"exampleFix":"// before\nconst coll = client.db(process.env.DB_NAME).collection(process.env.COLL_NAME);\n// DB_NAME unset => '' or undefined => MongoRuntimeError\n\n// after\nconst dbName = process.env.DB_NAME || 'app';\nconst collName = process.env.COLL_NAME || 'users';\nif (!dbName || !collName) throw new Error('DB and collection names are required');\nconst coll = client.db(dbName).collection(collName);","handlingStrategy":"validation","validationCode":"function requireNamespace(db: unknown, coll: unknown): { db: string; coll: string } {\n  if (typeof db !== 'string' || db === '') throw new Error('db name must be a non-empty string');\n  if (typeof coll !== 'string' || coll === '') throw new Error('collection name must be a non-empty string');\n  return { db, coll };\n}","typeGuard":"function isValidNamespace(s: unknown): s is string {\n  return typeof s === 'string' && s.length > 0 && /^[^.][^\\\\ ]*$/.test(s);\n}","tryCatchPattern":null,"preventionTips":["Always provide a fallback for env-derived names (process.env.DB_NAME || 'app').","Validate config objects at load time and fail fast with a clear message.","Unit-test config parsing to ensure names are non-empty strings."],"tags":["namespace","validation","configuration"],"analyzedSha":"3366c21a6311e02f1be91da982f9b93d3cce99a0","analyzedAt":"2026-08-04T13:40:15.335Z","schemaVersion":2}