mongodb/node-mongodb-native · error · MongoAPIError

collection ${this.namespace} not found

Error message

collection ${this.namespace} not found

What it means

Thrown by Collection.options() when listCollections returns no matching document, or the returned document has no options field. It is a MongoAPIError (note: despite the message text) emitted after a successful round-trip to the server, meaning the collection name does not exist in the database or is not a regular collection (e.g. a view, which has no 'options' field in the listCollections output).

Source

Thrown at src/collection.ts:592

      this.s.namespace,
      filter,
      resolveOptions(this, options)
    );
  }

  /**
   * Returns the options of the collection.
   *
   * @param options - Optional settings for the command
   */
  async options(options?: OperationOptions): Promise<Document> {
    options = resolveOptions(this, options);
    const [collection] = await this.db
      .listCollections({ name: this.collectionName }, { ...options, nameOnly: false })
      .toArray();

    if (collection == null || collection.options == null) {
      throw new MongoAPIError(`collection ${this.namespace} not found`);
    }

    return collection.options;
  }

  /**
   * Returns if the collection is a capped collection
   *
   * @param options - Optional settings for the command
   */
  async isCapped(options?: OperationOptions): Promise<boolean> {
    const { capped } = await this.options(options);
    return Boolean(capped);
  }

  /**
   * Creates an index on the db and collection collection.
   *

View on GitHub (pinned to 3366c21a63)

Solutions

1. Confirm the collection exists: run db.listCollections({name: '<name>'}).toArray() in mongosh.
2. Ensure at least one document has been written, or explicitly create the collection with db.createCollection('<name>').
3. Verify the database name in the connection string / client.db() call.
4. If introspecting views, handle the missing options case rather than relying on options().

Example fix

// before
const opts = await db.collection('maybeMissing').options();
// after
const [info] = await db.listCollections({ name: 'maybeMissing' }).toArray();
if (!info) {
  await db.createCollection('maybeMissing');
}
const opts = await db.collection('maybeMissing').options();

async function collectionExists(db: Db, name: string): Promise<boolean> {
  const list = await db.listCollections({ name }, { nameOnly: true }).toArray();
  return list.length > 0;
}
if (!(await collectionExists(db, 'myColl'))) {
  await db.createCollection('myColl');
}
const opts = await db.collection('myColl').options();

try {
  return await collection.options();
} catch (e) {
  if (e instanceof MongoAPIError && /collection .* not found/.test(e.message)) {
    return null; // treat missing as no options
  }
  throw e;
}

When it happens

Trigger: Calling collection.options() on a collection that was never created (MongoDB creates collections lazily on first write); calling it on a view; calling it against the wrong database name; a race where the collection was dropped between use and the options() call.

Common situations: Calling .options() or .isCapped() at startup to introspect a collection that has not been written yet; connecting to the wrong database in a multi-tenant deployment; collection name typo; calling isCapped() (which internally calls options()) on a non-existent collection.

Related errors

• Argument "docs" must be an array of documents
• Collection.insertMany() cannot be called with an array that
• Argument "operations" must be an array of documents
• Argument "pipeline" must be an array of aggregation stages
• Update operations require that all atomic operators have def

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