{"record":{"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/dce7939f86fb283e167ad709955abedb7bf23124/src/sessions.ts#L307-L343","documentation":"`advanceClusterTime` requires the document's `clusterTime` field to be a BSON Timestamp (`_bsontype === 'Timestamp'`). A missing field or any other type triggers MongoInvalidArgumentError. Server `$clusterTime` documents always carry a Timestamp here; the check fails when the document was rebuilt from JSON/plain objects.","triggerScenarios":"Forwarding a cluster time whose `clusterTime` was serialised to a plain object/number; manually constructing a cluster time doc without `new Timestamp(...)`; partially destructuring a server response.","commonSituations":"Multi-thread/process cluster-time sync over JSON transport (which strips BSON types); test fixtures that hand-build cluster time; reflection that loses prototype info.","solutions":["Transport cluster times via BSON serialisation, or rehydrate with `new Timestamp({ t: ct.clusterTime.high_, i: ct.clusterTime.low_ })` if you must cross JSON.","Forward the whole `$clusterTime` sub-document straight from the server response without modification.","Guard callers: `if (ct.clusterTime?._bsontype === 'Timestamp') session.advanceClusterTime(ct)`."],"exampleFix":"// before\nsession.advanceClusterTime({ clusterTime: { t: 1, i: 1 }, signature: {...} });\n\n// after\nimport { Timestamp } from 'mongodb';\nsession.advanceClusterTime({\n  clusterTime: new Timestamp({ t: 1, i: 1 }),\n  signature: { hash: ..., keyId: ... }\n});","handlingStrategy":"type-guard","validationCode":"import { Timestamp } from 'mongodb';\n\nfunction safeAdvance(session, ct) {\n  if (ct?.clusterTime?._bsontype === 'Timestamp') {\n    session.advanceClusterTime(ct);\n  }\n}","typeGuard":"function isValidClusterTime(v) {\n  return v != null && typeof v === 'object' &&\n    v.clusterTime?._bsontype === 'Timestamp';\n}","tryCatchPattern":null,"preventionTips":["Never round-trip cluster time through JSON; BSON-encode it.","Rehydrate Timestamp fields explicitly if you must reconstruct.","Forward the server's `$clusterTime` unmodified."],"tags":["sessions","cluster-time","bson","validation"],"backgroundTag":null,"analyzedSha":"dce7939f86fb283e167ad709955abedb7bf23124","analyzedAt":"2026-08-11T04:54:53.215Z","contentChangedAt":null,"schemaVersion":2},"datasetVersion":"2026-09-23T08:17:48.524Z"}