{"record":{"id":"da85d8bb7f9692a5","repo":"mongodb/node-mongodb-native","slug":"cannot-use-maxtimems-with-timeoutms-for-explain-co","errorCode":null,"errorMessage":"Cannot use maxTimeMS with timeoutMS for explain commands.","messagePattern":"Cannot use maxTimeMS with timeoutMS for explain commands\\.","errorType":"exception","errorClass":"MongoAPIError","httpStatus":null,"severity":"error","filePath":"src/explain.ts","lineNumber":96,"sourceCode":"    this.maxTimeMS = maxTimeMS;\n  }\n\n  static fromOptions({ explain }: ExplainOptions = {}): Explain | undefined {\n    if (explain == null) return;\n\n    if (typeof explain === 'boolean' || typeof explain === 'string') {\n      return new Explain(explain);\n    }\n\n    const { verbosity, maxTimeMS } = explain;\n    return new Explain(verbosity, maxTimeMS);\n  }\n}\n\nexport function validateExplainTimeoutOptions(options: Document, explain?: Explain) {\n  const { maxTimeMS, timeoutMS } = options;\n  if (timeoutMS != null && (maxTimeMS != null || explain?.maxTimeMS != null)) {\n    throw new MongoAPIError('Cannot use maxTimeMS with timeoutMS for explain commands.');\n  }\n}\n\n/**\n * Applies an explain to a given command.\n * @internal\n *\n * @param command - the command on which to apply the explain\n * @param options - the options containing the explain verbosity\n */\nexport function decorateWithExplain(\n  command: Document,\n  explain: Explain\n): {\n  explain: Document;\n  verbosity: ExplainVerbosity;\n  maxTimeMS?: number;\n} {","sourceCodeStart":78,"sourceCodeEnd":114,"githubUrl":"https://github.com/mongodb/node-mongodb-native/blob/dce7939f86fb283e167ad709955abedb7bf23124/src/explain.ts#L78-L114","documentation":"The driver's Client-Side Operation Timeout (CSOT) model treats timeoutMS as the overarching budget. For explain commands, specifying both maxTimeMS and timeoutMS is contradictory, so validateExplainTimeoutOptions (src/explain.ts:93) throws a MongoAPIError. This prevents two competing timeout semantics from being sent in the same command.","triggerScenarios":"Calling collection.find(..., { explain: { verbosity, maxTimeMS }, maxTimeMS, timeoutMS }) or aggregation explain with both maxTimeMS (either top-level or nested in explain) and timeoutMS set. Combining a globally configured timeoutMS with a per-call maxTimeMS on an explained command.","commonSituations":"Setting timeoutMS on the MongoClient and then passing maxTimeMS to a specific explain() call. Migrating from maxTimeMS to CSOT timeoutMS without removing the old maxTimeMS on explained queries.","solutions":["Remove maxTimeMS (both top-level and inside the explain option) when timeoutMS is set.","Or remove timeoutMS for this call and rely solely on maxTimeMS.","Avoid setting a global timeoutMS if you need per-command maxTimeMS control on explain queries."],"exampleFix":"// before\nawait coll.find({}, { explain: { verbosity: 'queryPlanner', maxTimeMS: 1000 }, timeoutMS: 5000 }).toArray();\n// after\nawait coll.find({}, { explain: { verbosity: 'queryPlanner' }, timeoutMS: 5000 }).toArray();","handlingStrategy":"validation","validationCode":"function reconcileTimeoutOptions(options) {\n  if (options?.timeoutMS != null) {\n    delete options.maxTimeMS;\n    if (options.explain && typeof options.explain === 'object') delete options.explain.maxTimeMS;\n  }\n  return options;\n}","typeGuard":"function hasConflictingTimeouts(options: any): boolean {\n  return options?.timeoutMS != null && (options?.maxTimeMS != null || options?.explain?.maxTimeMS != null);\n}","tryCatchPattern":"try {\n  await coll.find({}, opts).explain();\n} catch (e) {\n  if (e instanceof MongoAPIError && /maxTimeMS with timeoutMS/.test(e.message)) {\n    // remove maxTimeMS and retry\n  }\n  throw e;\n}","preventionTips":["Adopt a single timeout strategy per command: either timeoutMS (CSOT) or maxTimeMS, not both.","When setting a global timeoutMS, audit explain paths for per-call maxTimeMS.","Encapsulate timeout option resolution in one helper."],"tags":["timeout","csot","explain","configuration","synchronous"],"backgroundTag":null,"analyzedSha":"dce7939f86fb283e167ad709955abedb7bf23124","analyzedAt":"2026-08-11T04:54:53.215Z","contentChangedAt":null,"schemaVersion":2},"datasetVersion":"2026-09-23T08:17:48.524Z"}