{"id":"eed770f157d78006","repo":"mongodb/node-mongodb-native","slug":"input-cluster-time-clustertime-property-must-be","errorCode":null,"errorMessage":"input cluster time \"clusterTime\" property must be a valid BSON Timestamp","messagePattern":"input cluster time \"clusterTime\" property must be a valid BSON Timestamp","errorType":"exception","errorClass":"MongoInvalidArgumentError","httpStatus":null,"severity":"error","filePath":"src/sessions.ts","lineNumber":325,"sourceCode":"      return;\n    }\n\n    if (operationTime.greaterThan(this.operationTime)) {\n      this.operationTime = operationTime;\n    }\n  }\n\n  /**\n   * Advances the clusterTime for a ClientSession to the provided clusterTime of another ClientSession\n   *\n   * @param clusterTime - the $clusterTime returned by the server from another session in the form of a document containing the `BSON.Timestamp` clusterTime and signature\n   */\n  advanceClusterTime(clusterTime: ClusterTime): void {\n    if (!clusterTime || typeof clusterTime !== 'object') {\n      throw new MongoInvalidArgumentError('input cluster time must be an object');\n    }\n    if (!clusterTime.clusterTime || clusterTime.clusterTime._bsontype !== 'Timestamp') {\n      throw new MongoInvalidArgumentError(\n        'input cluster time \"clusterTime\" property must be a valid BSON Timestamp'\n      );\n    }\n    if (\n      !clusterTime.signature ||\n      clusterTime.signature.hash?._bsontype !== 'Binary' ||\n      (typeof clusterTime.signature.keyId !== 'bigint' &&\n        typeof clusterTime.signature.keyId !== 'number' &&\n        clusterTime.signature.keyId?._bsontype !== 'Long') // apparently we decode the key to number?\n    ) {\n      throw new MongoInvalidArgumentError(\n        'input cluster time must have a valid \"signature\" property with BSON Binary hash and BSON Long keyId'\n      );\n    }\n\n    _advanceClusterTime(this, clusterTime);\n  }\n","sourceCodeStart":307,"sourceCodeEnd":343,"githubUrl":"https://github.com/mongodb/node-mongodb-native/blob/3366c21a6311e02f1be91da982f9b93d3cce99a0/src/sessions.ts#L307-L343","documentation":"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.","triggerScenarios":"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.","commonSituations":"JSON round-tripping cluster times (BSON types are lost); constructing cluster-time docs by hand; forwarding a cluster time from a non-BSON source.","solutions":["Always pass the original server `$clusterTime` document, which already contains a BSON Timestamp.","If reconstructing, build the Timestamp with `new BSON.Timestamp({ t, i })`.","Avoid JSON-serializing cluster times; keep them as BSON documents end-to-end."],"exampleFix":"// before\nsession.advanceClusterTime({ clusterTime: 12345, signature: {...} });\n// after\nconst { Timestamp } = require('bson');\nsession.advanceClusterTime({ clusterTime: new Timestamp({ t: 12345, i: 1 }), signature: {...} });","handlingStrategy":"type-guard","validationCode":"function advanceClusterTimeSafe(session, ct) {\n  if (!(ct?.clusterTime?._bsontype === 'Timestamp')) {\n    throw new TypeError('clusterTime.clusterTime must be a BSON.Timestamp');\n  }\n  return session.advanceClusterTime(ct);\n}","typeGuard":"function isBsonTimestampClusterTime(ct) {\n  return ct?.clusterTime?._bsontype === 'Timestamp';\n}","tryCatchPattern":null,"preventionTips":["Always pass the server's $clusterTime document which already has a BSON Timestamp.","Never JSON-serialize cluster times; keep BSON types intact.","When reconstructing, build with new BSON.Timestamp({ t, i })."],"tags":["sessions","validation","bson"],"analyzedSha":"3366c21a6311e02f1be91da982f9b93d3cce99a0","analyzedAt":"2026-08-04T13:40:15.335Z","schemaVersion":2}