mongodb/node-mongodb-native · error · MongoInvalidArgumentError

Properties "causalConsistency" and "snapshot" are mutually e

Error message

Properties "causalConsistency" and "snapshot" are mutually exclusive

What it means

Thrown by the ClientSession constructor when both `causalConsistency: true` and `snapshot: true` are passed to `startSession` (sessions.ts:179). Causal consistency and snapshot reads are distinct session semantics that cannot be combined: snapshot reads capture a single consistent point-in-time view, while causal consistency sequences reads/writes by causality.

Source

Thrown at src/sessions.ts:180

  ) {
    super();
    this.on('error', noop);

    if (client == null) {
      // TODO(NODE-3483)
      throw new MongoRuntimeError('ClientSession requires a MongoClient');
    }

    if (sessionPool == null || !(sessionPool instanceof ServerSessionPool)) {
      // TODO(NODE-3483)
      throw new MongoRuntimeError('ClientSession requires a ServerSessionPool');
    }

    options = options ?? {};

    this.snapshotEnabled = options.snapshot === true;
    if (options.causalConsistency === true && this.snapshotEnabled) {
      throw new MongoInvalidArgumentError(
        'Properties "causalConsistency" and "snapshot" are mutually exclusive'
      );
    }

    this.client = client;
    this.sessionPool = sessionPool;
    this.hasEnded = false;
    this.clientOptions = clientOptions;
    this.timeoutMS = options.defaultTimeoutMS ?? client.s.options?.timeoutMS;

    this.explicit = !!options.explicit;
    this._serverSession = this.explicit ? this.sessionPool.acquire() : null;
    this.txnNumberIncrement = 0;

    const defaultCausalConsistencyValue = this.explicit && options.snapshot !== true;
    this.supports = {
      // if we can enable causal consistency, do so by default
      causalConsistency: options.causalConsistency ?? defaultCausalConsistencyValue

View on GitHub (pinned to 3366c21a63)

Solutions

1. Pick one: use `{ snapshot: true }` for snapshot reads or `{ causalConsistency: true }` for causal sessions.
2. Audit shared/default session option builders to ensure the two are not both set.
3. Remember causalConsistency defaults to true for explicit non-snapshot sessions, so setting snapshot requires explicitly leaving causalConsistency unset/false.

Example fix

// before
const session = client.startSession({ causalConsistency: true, snapshot: true });
// after
const session = client.startSession({ snapshot: true });

function sessionOptions(opts = {}) {
  if (opts.causalConsistency === true && opts.snapshot === true) {
    throw new TypeError('causalConsistency and snapshot are mutually exclusive');
  }
  return opts;
}

function areSessionOptionsCompatible(opts) {
  return !(opts.causalConsistency === true && opts.snapshot === true);
}

When it happens

Trigger: Calling `client.startSession({ causalConsistency: true, snapshot: true })`; merging option objects where both flags end up true.

Common situations: Copy-pasting session options; enabling snapshot reads for a transaction while leaving causalConsistency on; defaults from a shared config object colliding.

Related errors

• Missing required option `keyVaultNamespace`
• Invalid CANONICALIZE_HOST_NAME value: ${canonicalization}
• TOKEN_RESOURCE must be set in the auth mechanism properties
• User provided OIDC callbacks must return a valid object with
• TOKEN_RESOURCE must be set in the auth mechanism properties

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