mongodb/node-mongodb-native · error · MongoCompatibilityError

Snapshot reads require MongoDB 5.0 or later

Error message

Snapshot reads require MongoDB 5.0 or later

What it means

Thrown when a session has snapshotEnabled (readConcern level 'snapshot') but the connected server's wire version is below MIN_SUPPORTED_SNAPSHOT_READS_WIRE_VERSION (13, i.e. MongoDB 5.0). Snapshot reads require server-side support for snapshot transaction semantics, so the driver refuses the operation.

Solutions

  1. Upgrade the server to MongoDB 5.0 or later (wire version 13+).
  2. If upgrade is not possible, omit snapshot: true from startSession options and from defaultSession options.
  3. Verify with db.hello().maxWireVersion >= 13 before starting a snapshot session.

Example fix

// before — server is 4.4
const session = client.startSession({ snapshot: true });
await collection.findOne({}, { session });

// after — upgrade server to 5.0+, then the same call works
Defensive patterns

Strategy: validation

Validate before calling

const hello = await db.command('hello');
if (sessionOptions?.snapshot && hello.maxWireVersion < 13) {
  throw new Error('Snapshot reads require MongoDB 5.0+ (wire version 13)');
}
const session = client.startSession(sessionOptions);

Prevention

When it happens

Trigger: Calling client.startSession({ snapshot: true }) and running operations against a 4.4-or-earlier server; inheriting snapshot from client defaults on an older cluster.

Common situations: Local dev on MongoDB 4.4; connecting to an Atlas M0 tier that is pinned to an older major; upgrading the driver to a version that enables snapshot by default in some path.

Related errors

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

Appendix: source

Thrown at src/operations/execute_operation.ts:93

    client.topology == null
      ? await abortable(autoConnect(client), operation.options)
      : client.topology;

  // The driver sessions spec mandates that we implicitly create sessions for operations
  // that are not explicitly provided with a session.
  let session = operation.session;
  let owner: symbol | undefined;

  if (session == null) {
    owner = Symbol();
    session = client.startSession({ owner, explicit: false });
  } else if (session.hasEnded) {
    throw new MongoExpiredSessionError('Use of expired sessions is not permitted');
  } else if (
    session.snapshotEnabled &&
    maxWireVersion(topology) < MIN_SUPPORTED_SNAPSHOT_READS_WIRE_VERSION
  ) {
    throw new MongoCompatibilityError('Snapshot reads require MongoDB 5.0 or later');
  } else if (session.client !== client) {
    throw new MongoInvalidArgumentError('ClientSession must be from the same MongoClient');
  }

  operation.session ??= session;

  const readPreference = operation.readPreference ?? ReadPreference.primary;
  const inTransaction = !!session?.inTransaction();

  const hasReadAspect = operation.hasAspect(Aspect.READ_OPERATION);

  if (
    inTransaction &&
    !readPreference.equals(ReadPreference.primary) &&
    (hasReadAspect || operation.commandName === 'runCommand')
  ) {
    throw new MongoTransactionError(
      `Read preference in a transaction must be primary, not: ${readPreference.mode}`

View on GitHub (pinned to dce7939f86)