mongodb/node-mongodb-native · error · MongoAPIError

collection not found

Error message

collection ${this.namespace} not found

What it means

Thrown by Collection.options when listCollections does not return a document (or a document without options) for the collection name. It runs db.listCollections filtered by name and, if nothing matches, raises a MongoAPIError that the collection was not found. This is a runtime/server-state condition, not an argument-type error.

Solutions

1. Ensure the collection exists by performing a write first or running createCollection.
2. Verify the database name and collection name in the MongoClient URI/hierarchy.
3. Check that the authenticated user has listCollections privileges.
4. Guard the call with a check or create the collection explicitly if optional.

Example fix

// before
const opts = await db.collection('maybeMissing').options();

// after
const coll = db.collection('maybeMissing');
try {
  return await coll.options();
} catch (e) {
  if (e instanceof MongoAPIError && /not found/.test(e.message)) return null;
  throw e;
}

const exists = await db.listCollections({ name: coll.collectionName }, { nameOnly: true }).hasNext();
if (!exists) return null;
return await coll.options();

try {
  return await coll.options();
} catch (e) {
  if (e instanceof MongoAPIError && /not found/.test(e.message)) return null;
  throw e;
}

When it happens

Trigger: Fires at src/collection.ts:592 when the filtered listCollections cursor yields no document or one whose options field is null/undefined. Called by collection.options() and indirectly by isCapped and other metadata-dependent methods.

Common situations: Calling .options() on a collection that has never been created (MongoDB creates lazily on first write, so a write-less collection may not exist); connecting to the wrong database; insufficient permissions to list collections (auth); the collection was dropped between calls; a typo in the collection name.

Related errors

• Credentials required for GSSAPI authentication
• Host ' ' is not valid for OIDC authentication with…
• username and ENVIRONMENT
• Username required for mechanism
• Auth mechanism property ALLOWED_HOSTS is not allowed in the…

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

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