MongoDB Memory Server Core

Common errors

• Error: A MongoDB binary could not be found.

  cause The `mongodb-memory-server-core` package does not download the MongoDB binary by default, and it was not found in expected locations or configured paths.
  fix Use the full `mongodb-memory-server` package, which includes binary autodownload. Alternatively, set the `MONGOMS_DOWNLOAD_DIR` environment variable to a path where binaries should be downloaded, or `MONGOMS_SYSTEM_BINARY` to the path of an existing MongoDB executable.

• MongoServerError: No primary found for replica set rs0

  cause This typically occurs when a `MongoMemoryReplSet` is used, but the replica set hasn't fully initialized or achieved a primary state before the client attempts to connect or perform operations.
  fix Ensure you `await` the `start()` method of `MongoMemoryReplSet` and consider adding a small delay or a retry mechanism for client connections in your tests to account for replica set election time.

• ERR_REQUIRE_ESM: require() of ES Module ...mongodb-memory-server-core/index.js from ... not supported.

  cause The package `mongodb-memory-server-core` is an ECMAScript Module (ESM) and cannot be imported using `require()` in newer Node.js environments (v20.19.0+) that strictly enforce ESM.
  fix Update your import statements to use ESM `import` syntax: `import { MongoMemoryServer } from 'mongodb-memory-server-core';`. Ensure your project is configured for ESM (e.g., `"type": "module"` in `package.json`).

• Error: Node.js v18.x.x is not supported! Please use Node.js v20.19.0 or newer.

  cause Attempting to run `mongodb-memory-server-core` v11+ with an unsupported Node.js version, as indicated by the breaking change.
  fix Upgrade your Node.js runtime to version 20.19.0 or a newer compatible version. Check the `engines.node` field in the `package.json` for current requirements.

Warnings

• breaking Version 11.0.0 removed support for Node.js versions below 20.19.0. Projects using older Node.js runtimes must upgrade their environment or stick to `mongodb-memory-server-core` v10.x.x.
  Fix: Upgrade your Node.js environment to version 20.19.0 or newer. Alternatively, pin `mongodb-memory-server-core` to a version prior to 11.0.0.
• breaking The default MongoDB binary version used by `mongodb-memory-server-core` (when not explicitly configured) was updated to 8.2.x in v11.0.0. This might cause compatibility issues if your application or driver expects an older MongoDB version.
  Fix: Explicitly define the desired MongoDB version using the `version` option in the `create` or `start` method, e.g., `MongoMemoryServer.create({ instance: { version: '6.0.0' } })`.
• breaking Support for MongoDB binary versions below 4.2.0 was removed in version 11.0.0.
  Fix: Ensure your tests use MongoDB versions 4.2.0 or newer. If older versions are strictly required, you must use `mongodb-memory-server-core` v10.x.x or earlier.
• breaking The `tsconfig` target was upgraded to `es2023` in version 11.0.0, which could cause compilation issues in projects targeting older ECMAScript versions or using outdated TypeScript configurations.
  Fix: Update your project's TypeScript configuration to target `es2023` or newer, and ensure your TypeScript compiler is up-to-date (typically TypeScript 5.x or newer).
• gotcha This is the 'core' package (`mongodb-memory-server-core`) and it *does not* automatically download the MongoDB binary. Users are responsible for providing the binary, either manually or via another package like `mongodb-memory-server` (the meta-package).
  Fix: If you expect automatic binary downloads, use the `mongodb-memory-server` package directly. If using `mongodb-memory-server-core`, ensure the `MONGOMS_DOWNLOAD_DIR` or `MONGOMS_SYSTEM_BINARY` environment variables are correctly configured, or manage the binary installation externally.

Install

• npm install mongodb-memory-server-core npm
• yarn add mongodb-memory-server-core yarn
• pnpm add mongodb-memory-server-core pnpm

Imports

• MongoMemoryServer
  wrong:

  const { MongoMemoryServer } = require('mongodb-memory-server-core');

  correct:

  import { MongoMemoryServer } from 'mongodb-memory-server-core';

  The library primarily targets ESM environments since Node.js 20.19.0 and tsconfig es2023 in v11.
• MongoMemoryReplSet
  wrong:

  import MongoMemoryReplSet from 'mongodb-memory-server-core';

  correct:

  import { MongoMemoryReplSet } from 'mongodb-memory-server-core';

  Used for testing applications that require a MongoDB replica set configuration, imported as a named export.
• StartOptions

  import type { StartOptions } from 'mongodb-memory-server-core';

  Type import for configuration options when starting the server or replica set.

Quickstart

Demonstrates starting an in-memory MongoDB server, connecting with the official driver, performing a basic insert and find operation, and properly shutting down the client and server.

import { MongoMemoryServer } from 'mongodb-memory-server-core';
import { MongoClient } from 'mongodb';

async function runInMemoryMongo() {
  let mongod: MongoMemoryServer | undefined;
  let client: MongoClient | undefined;

  try {
    mongod = await MongoMemoryServer.create();
    const uri = mongod.getUri();
    console.log(`MongoDB Memory Server started at: ${uri}`);

    client = new MongoClient(uri);
    await client.connect();
    console.log('Connected to MongoDB Memory Server.');

    const db = client.db('testdb');
    const collection = db.collection('documents');

    await collection.insertOne({ name: 'Test Document', value: 123 });
    const doc = await collection.findOne({ name: 'Test Document' });
    console.log('Found document:', doc);

  } catch (error) {
    console.error('Error during in-memory MongoDB operation:', error);
  } finally {
    if (client) {
      await client.close();
      console.log('MongoDB client closed.');
    }
    if (mongod) {
      await mongod.stop();
      console.log('MongoDB Memory Server stopped.');
    }
  }
}

runInMemoryMongo();