mongodb/node-mongodb-native · error · MongoInvalidArgumentError

Properties "causalConsistency" and "snapshot" are mutually…

Error message

Properties "causalConsistency" and "snapshot" are mutually exclusive

What it means

Per the Driver Sessions Spec, a session cannot be both causally consistent and a snapshot session — they use different read guarantee semantics. The ClientSession constructor throws MongoInvalidArgumentError when `options.causalConsistency === true && options.snapshot === true`.

Solutions

1. Pick one mode: `{ snapshot: true }` for snapshot reads, or `{ causalConsistency: true }` (the default for explicit non-snapshot sessions) for causal consistency.
2. Audit option-merging code so a stale `causalConsistency: true` is not combined with a new `snapshot: true`.
3. Build the options object conditionally: `const opts = useSnapshot ? { snapshot: true } : { causalConsistency: true }`.

Example fix

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

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

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

When it happens

Trigger: Calling `client.startSession({ causalConsistency: true, snapshot: true })`.

Common situations: Copy-pasting options between a snapshot read flow and a causal-consistency flow; enabling snapshot reads defensively while keeping causal consistency on; refactor that merges two option objects.

Related errors

• Cannot call abortTransaction after calling commitTransaction
• Cannot call abortTransaction twice
• Cannot call commitTransaction after calling abortTransaction
• ClientSession requires a MongoClient
• ClientSession requires a ServerSessionPool

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

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