{"record":{"id":"2a1e8451cd487c9e","repo":"mongodb/node-mongodb-native","slug":"input-cluster-time-must-be-an-object","errorCode":null,"errorMessage":"input cluster time must be an object","messagePattern":"input cluster time must be an object","errorType":"exception","errorClass":"MongoInvalidArgumentError","httpStatus":null,"severity":"error","filePath":"src/sessions.ts","lineNumber":322,"sourceCode":"  advanceOperationTime(operationTime: Timestamp): void {\n    if (this.operationTime == null) {\n      this.operationTime = operationTime;\n      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","sourceCodeStart":304,"sourceCodeEnd":340,"githubUrl":"https://github.com/mongodb/node-mongodb-native/blob/dce7939f86fb283e167ad709955abedb7bf23124/src/sessions.ts#L304-L340","documentation":"`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.","triggerScenarios":"Calling `session.advanceClusterTime(null)`, `advanceClusterTime('xyz')`, or `advanceClusterTime(123)`; passing a value deserialised from JSON without rehydrating BSON types.","commonSituations":"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.","solutions":["Only call `advanceClusterTime` with the `$clusterTime` document returned by the server (already correct shape).","Add a null/type guard before forwarding: `if (ct && typeof ct === 'object') session.advanceClusterTime(ct)`.","When propagating across processes, use BSON serialisation so nested Timestamp/Binary types survive."],"exampleFix":"// before\nsession.advanceClusterTime(maybeClusterTime);\n\n// after\nif (maybeClusterTime && typeof maybeClusterTime === 'object') {\n  session.advanceClusterTime(maybeClusterTime);\n}","handlingStrategy":"validation","validationCode":"function forwardClusterTime(session, clusterTime) {\n  if (!clusterTime || typeof clusterTime !== 'object') return;\n  session.advanceClusterTime(clusterTime);\n}","typeGuard":"function isClusterTimeDoc(v) {\n  return v != null && typeof v === 'object' &&\n    'clusterTime' in v && 'signature' in v;\n}","tryCatchPattern":null,"preventionTips":["Forward `$clusterTime` documents verbatim from server responses.","Validate the shape before calling advanceClusterTime.","Use BSON serialisation when transporting cluster time across processes."],"tags":["sessions","cluster-time","validation","bson"],"backgroundTag":null,"analyzedSha":"dce7939f86fb283e167ad709955abedb7bf23124","analyzedAt":"2026-08-11T04:54:53.215Z","contentChangedAt":null,"schemaVersion":2},"datasetVersion":"2026-09-23T08:17:48.524Z"}