{"id":"c380e09882d6be7f","repo":"mongodb/node-mongodb-native","slug":"expired-after-this-timeoutms-ms","errorCode":null,"errorMessage":"Expired after ${this.timeoutMS}ms","messagePattern":"Expired after (.+?)ms","errorType":"exception","errorClass":"MongoOperationTimeoutError","httpStatus":null,"severity":"error","filePath":"src/timeout.ts","lineNumber":314,"sourceCode":"    this.minRoundTripTime = 0;\n    this._serverSelectionTimeout?.clear();\n    this._connectionCheckoutTimeout?.clear();\n  }\n\n  clear(): void {\n    this._serverSelectionTimeout?.clear();\n    this._connectionCheckoutTimeout?.clear();\n  }\n\n  /**\n   * @internal\n   * Throws a MongoOperationTimeoutError if the context has expired.\n   * If the context has not expired, returns the `remainingTimeMS`\n   **/\n  getRemainingTimeMSOrThrow(message?: string): number {\n    const { remainingTimeMS } = this;\n    if (remainingTimeMS <= 0)\n      throw new MongoOperationTimeoutError(message ?? `Expired after ${this.timeoutMS}ms`);\n    return remainingTimeMS;\n  }\n\n  /**\n   * @internal\n   * This method is intended to be used in situations where concurrent operation are on the same deadline, but cannot share a single `TimeoutContext` instance.\n   * Returns a new instance of `CSOTTimeoutContext` constructed with identical options, but setting the `start` property to `this.start`.\n   */\n  clone(): CSOTTimeoutContext {\n    const timeoutContext = new CSOTTimeoutContext({\n      timeoutMS: this.timeoutMS,\n      serverSelectionTimeoutMS: this.serverSelectionTimeoutMS\n    });\n    timeoutContext.start = this.start;\n    return timeoutContext;\n  }\n\n  override refreshed(): CSOTTimeoutContext {","sourceCodeStart":296,"sourceCodeEnd":332,"githubUrl":"https://github.com/mongodb/node-mongodb-native/blob/3366c21a6311e02f1be91da982f9b93d3cce99a0/src/timeout.ts#L296-L332","documentation":"Thrown by the @internal CSOTTimeoutContext.getRemainingTimeMSOrThrow() when remainingTimeMS <= 0, i.e. the CSOT deadline has passed. The message includes the original timeoutMS. It surfaces as a MongoOperationTimeoutError and is the primary way CSOT-enforced operations fail once their budget is exhausted.","triggerScenarios":"Any operation running under timeoutMS (CSOT) whose wall-clock budget runs out before completion: slow queries, long server selection, slow connection checkout, or chained operations sharing one deadline.","commonSituations":"Setting an aggressive timeoutMS on heavy aggregations/queries; network latency or cluster load pushing operations past the budget; sequential operations inside withTransaction({ timeoutMS }) exhausting the shared budget.","solutions":["Increase timeoutMS to match realistic operation latency.","Optimize the operation (indexes, $project to reduce payload, narrower filters) to fit the budget.","For transactions, size timeoutMS to the whole transaction, not a single op, since withTransaction shares one deadline.","Scale the cluster (more CPU/replicas) if the workload legitimately needs more time."],"exampleFix":"// before\nawait coll.aggregate([ /* heavy pipeline */ ], { timeoutMS: 1000 }).toArray(); // throws Expired after 1000ms\n\n// after\nawait coll.aggregate([ /* heavy pipeline */ ], { timeoutMS: 60_000 }).toArray();","handlingStrategy":"retry","validationCode":"// size timeoutMS to realistic latency; budget the whole transaction\nconst timeoutMS = Math.max(30_000, estimatedMs * 3);\nawait coll.find({}, { timeoutMS }).toArray();","typeGuard":"import { MongoOperationTimeoutError } from 'mongodb';\nfunction isOperationTimeout(e: unknown): e is MongoOperationTimeoutError {\n  return e instanceof MongoOperationTimeoutError;\n}","tryCatchPattern":"try {\n  await coll.aggregate(pipeline, { timeoutMS: 5_000 }).toArray();\n} catch (e) {\n  if (isOperationTimeout(e)) {\n    // retry with a larger budget or surface 'query too slow for deadline'\n    await coll.aggregate(pipeline, { timeoutMS: 60_000 }).toArray();\n  } else throw e;\n}","preventionTips":["Set timeoutMS from measured latency, with headroom (e.g. 3x p99).","Index and $project to keep operations inside the budget.","For withTransaction, allocate timeoutMS across all ops in the callback."],"tags":["timeout","csot","operation-timeout","deadline","performance"],"analyzedSha":"3366c21a6311e02f1be91da982f9b93d3cce99a0","analyzedAt":"2026-08-04T13:40:15.335Z","schemaVersion":2}