{"record":{"id":"d4d3410387a0961f","repo":"mongodb/node-mongodb-native","slug":"server-reported-a-timeout-error","errorCode":null,"errorMessage":"Server reported a timeout error","messagePattern":"Server reported a timeout error","errorType":"exception","errorClass":"MongoOperationTimeoutError","httpStatus":null,"severity":"error","filePath":"src/cmap/connection.ts","lineNumber":559,"sourceCode":"    let document: MongoDBResponse | undefined = undefined;\n    /** Cached result of a toObject call */\n    let object: Document | undefined = undefined;\n    try {\n      this.throwIfAborted();\n      for await (document of this.sendWire(message, options, responseType)) {\n        object = undefined;\n        if (options.session != null) {\n          updateSessionFromResponse(options.session, document);\n        }\n\n        if (document.$clusterTime) {\n          this.clusterTime = document.$clusterTime;\n          this.emit(Connection.CLUSTER_TIME_RECEIVED, document.$clusterTime);\n        }\n\n        if (document.ok === 0) {\n          if (options.timeoutContext?.csotEnabled() && document.isMaxTimeExpiredError) {\n            throw new MongoOperationTimeoutError('Server reported a timeout error', {\n              cause: new MongoServerError((object ??= document.toObject(bsonOptions)))\n            });\n          }\n          throw new MongoServerError((object ??= document.toObject(bsonOptions)));\n        }\n\n        if (this.shouldEmitAndLogCommand) {\n          this.emitAndLogCommand(\n            this.monitorCommands,\n            Connection.COMMAND_SUCCEEDED,\n            message.databaseName,\n            this.established,\n            new CommandSucceededEvent(\n              this,\n              message,\n              message.moreToCome ? { ok: 1 } : (object ??= document.toObject(bsonOptions)),\n              started,\n              this.description.serverConnectionId","sourceCodeStart":541,"sourceCodeEnd":577,"githubUrl":"https://github.com/mongodb/node-mongodb-native/blob/dce7939f86fb283e167ad709955abedb7bf23124/src/cmap/connection.ts#L541-L577","documentation":"A MongoOperationTimeoutError thrown inside Connection.sendCommand when the server returns a document with ok === 0, CSOT is enabled, and the response is identified as a maxTimeMS-expired error. The original server error is wrapped as the cause so callers can inspect both the CSOT framing and the underlying MongoServerError.","triggerScenarios":"An operation runs under CSOT (timeoutMS set), the server receives maxTimeMS (derived from the remaining budget) and the query exceeds it server-side, returning a MaxTimeMSExpired-style error. The driver converts this into a MongoOperationTimeoutError to present a uniform timeout surface.","commonSituations":"Long-running aggregations or finds with a small timeoutMS; server under load causing queries to exceed the derived maxTimeMS; using timeoutMS where legacy socketTimeoutMS was previously used with more headroom.","solutions":["Increase timeoutMS for the operation or the client.","Optimize the query: add indexes, use $limit, or restructure the aggregation pipeline.","Check server load and slow-query logs; the cause field carries the server's error details.","Use operation-level timeoutMS only where needed rather than a tiny global timeout."],"exampleFix":"// before\nawait coll.find({}).maxTimeMS(100).toArray(); // server-enforced, may 122 under CSOT\n\n// after\nawait coll.find({}, { timeoutMS: 30000 }).toArray();","handlingStrategy":"try-catch","validationCode":null,"typeGuard":"function isCSOTTimeout(e: unknown): e is MongoOperationTimeoutError {\n  return e instanceof MongoOperationTimeoutError && /Server reported a timeout/.test(e.message);\n}","tryCatchPattern":"try {\n  await cursor.toArray();\n} catch (e) {\n  if (e instanceof MongoOperationTimeoutError) {\n    // increase timeoutMS or optimize query, then retry\n  } else throw e;\n}","preventionTips":["Set timeoutMS comfortably above expected query duration.","Add indexes to keep queries within budget.","Use $limit and early $project in aggregations."],"tags":["timeout","csot","query","maxtimems"],"backgroundTag":null,"analyzedSha":"dce7939f86fb283e167ad709955abedb7bf23124","analyzedAt":"2026-08-11T04:54:53.215Z","contentChangedAt":null,"schemaVersion":2},"datasetVersion":"2026-09-23T08:17:48.524Z"}