mongodb/node-mongodb-native · error · MongoInvalidArgumentError

input cluster time must be an object

Error message

input cluster time must be an object

What it means

`ClientSession.advanceClusterTime` validates its argument shape: it must be a non-null object. If the argument is falsy or not an object, MongoInvalidArgumentError is thrown. The driver normally calls this internally with `$clusterTime` docs from the server; user code only hits it when forwarding cluster times between sessions manually.

Solutions

1. Only call `advanceClusterTime` with the `$clusterTime` document returned by the server (already correct shape).
2. Add a null/type guard before forwarding: `if (ct && typeof ct === 'object') session.advanceClusterTime(ct)`.
3. When propagating across processes, use BSON serialisation so nested Timestamp/Binary types survive.

Example fix

// before
session.advanceClusterTime(maybeClusterTime);

// after
if (maybeClusterTime && typeof maybeClusterTime === 'object') {
  session.advanceClusterTime(maybeClusterTime);
}

function forwardClusterTime(session, clusterTime) {
  if (!clusterTime || typeof clusterTime !== 'object') return;
  session.advanceClusterTime(clusterTime);
}

function isClusterTimeDoc(v) {
  return v != null && typeof v === 'object' &&
    'clusterTime' in v && 'signature' in v;
}

When it happens

Trigger: Calling `session.advanceClusterTime(null)`, `advanceClusterTime('xyz')`, or `advanceClusterTime(123)`; passing a value deserialised from JSON without rehydrating BSON types.

Common situations: Custom multi-client cluster-time synchronisation logic that forgot a null check; serialising cluster time through JSON and feeding the result back; an off-by-one in forwarding logic.

Related errors

• input cluster time "clusterTime" property must be a valid…
• input cluster time must have a valid "signature" property…
• Cannot call abortTransaction after calling commitTransaction
• Cannot call abortTransaction twice
• Cannot call commitTransaction after calling abortTransaction

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

Appendix: source

Thrown at src/sessions.ts:322

  advanceOperationTime(operationTime: Timestamp): void {
    if (this.operationTime == null) {
      this.operationTime = operationTime;
      return;
    }

    if (operationTime.greaterThan(this.operationTime)) {
      this.operationTime = operationTime;
    }
  }

  /**
   * Advances the clusterTime for a ClientSession to the provided clusterTime of another ClientSession
   *
   * @param clusterTime - the $clusterTime returned by the server from another session in the form of a document containing the `BSON.Timestamp` clusterTime and signature
   */
  advanceClusterTime(clusterTime: ClusterTime): void {
    if (!clusterTime || typeof clusterTime !== 'object') {
      throw new MongoInvalidArgumentError('input cluster time must be an object');
    }
    if (!clusterTime.clusterTime || clusterTime.clusterTime._bsontype !== 'Timestamp') {
      throw new MongoInvalidArgumentError(
        'input cluster time "clusterTime" property must be a valid BSON Timestamp'
      );
    }
    if (
      !clusterTime.signature ||
      clusterTime.signature.hash?._bsontype !== 'Binary' ||
      (typeof clusterTime.signature.keyId !== 'bigint' &&
        typeof clusterTime.signature.keyId !== 'number' &&
        clusterTime.signature.keyId?._bsontype !== 'Long') // apparently we decode the key to number?
    ) {
      throw new MongoInvalidArgumentError(
        'input cluster time must have a valid "signature" property with BSON Binary hash and BSON Long keyId'
      );
    }

View on GitHub (pinned to dce7939f86)