mongodb/node-mongodb-native · error · MongoInvalidArgumentError

input cluster time "clusterTime" property must be a valid BS

Error message

input cluster time "clusterTime" property must be a valid BSON Timestamp

What it means

Thrown by `advanceClusterTime` when the object's `clusterTime` field is missing or is not a BSON `Timestamp` instance (`_bsontype === 'Timestamp'`) (sessions.ts:324). The cluster time is a vector clock carried as a BSON Timestamp; a plain number, Long, or string is not acceptable because it must serialize identically on the wire.

Source

Thrown at src/sessions.ts:325

      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'
      );
    }

    _advanceClusterTime(this, clusterTime);
  }

View on GitHub (pinned to 3366c21a63)

Solutions

1. Always pass the original server `$clusterTime` document, which already contains a BSON Timestamp.
2. If reconstructing, build the Timestamp with `new BSON.Timestamp({ t, i })`.
3. Avoid JSON-serializing cluster times; keep them as BSON documents end-to-end.

Example fix

// before
session.advanceClusterTime({ clusterTime: 12345, signature: {...} });
// after
const { Timestamp } = require('bson');
session.advanceClusterTime({ clusterTime: new Timestamp({ t: 12345, i: 1 }), signature: {...} });

function advanceClusterTimeSafe(session, ct) {
  if (!(ct?.clusterTime?._bsontype === 'Timestamp')) {
    throw new TypeError('clusterTime.clusterTime must be a BSON.Timestamp');
  }
  return session.advanceClusterTime(ct);
}

function isBsonTimestampClusterTime(ct) {
  return ct?.clusterTime?._bsontype === 'Timestamp';
}

When it happens

Trigger: Passing `{ clusterTime: 12345 }` (a number) instead of `{ clusterTime: new Timestamp({ t: 12345, i: 1 }) }`; deserializing a cluster time from JSON so the Timestamp becomes a plain number; copying only part of the `$clusterTime` document.

Common situations: JSON round-tripping cluster times (BSON types are lost); constructing cluster-time docs by hand; forwarding a cluster time from a non-BSON source.

Related errors

• Properties "causalConsistency" and "snapshot" are mutually e
• input cluster time must be an object
• input cluster time must have a valid "signature" property wi
• ClientSession cannot be serialized to BSON.
• Update document requires atomic operators

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