{"id":"0ad9484ef35a494f","repo":"mongodb/node-mongodb-native","slug":"argument-for-maxtimems-must-be-a-number","errorCode":null,"errorMessage":"Argument for maxTimeMS must be a number","messagePattern":"Argument for maxTimeMS must be a number","errorType":"exception","errorClass":"MongoInvalidArgumentError","httpStatus":null,"severity":"error","filePath":"src/cursor/abstract_cursor.ts","lineNumber":789,"sourceCode":"  withReadConcern(readConcern: ReadConcernLike): this {\n    this.throwIfInitialized();\n    const resolvedReadConcern = ReadConcern.fromOptions({ readConcern });\n    if (resolvedReadConcern) {\n      this.cursorOptions.readConcern = resolvedReadConcern;\n    }\n\n    return this;\n  }\n\n  /**\n   * Set a maxTimeMS on the cursor query, allowing for hard timeout limits on queries (Only supported on MongoDB 2.6 or higher)\n   *\n   * @param value - Number of milliseconds to wait before aborting the query.\n   */\n  maxTimeMS(value: number): this {\n    this.throwIfInitialized();\n    if (typeof value !== 'number') {\n      throw new MongoInvalidArgumentError('Argument for maxTimeMS must be a number');\n    }\n\n    this.cursorOptions.maxTimeMS = value;\n    return this;\n  }\n\n  /**\n   * Set the batch size for the cursor.\n   *\n   * @param value - The number of documents to return per batch. See {@link https://www.mongodb.com/docs/manual/reference/command/find/|find command documentation}.\n   */\n  batchSize(value: number): this {\n    this.throwIfInitialized();\n    if (this.cursorOptions.tailable) {\n      throw new MongoTailableCursorError('Tailable cursor does not support batchSize');\n    }\n\n    if (typeof value !== 'number') {","sourceCodeStart":771,"sourceCodeEnd":807,"githubUrl":"https://github.com/mongodb/node-mongodb-native/blob/3366c21a6311e02f1be91da982f9b93d3cce99a0/src/cursor/abstract_cursor.ts#L771-L807","documentation":"Thrown by cursor.maxTimeMS(value) when value is not of type 'number'. maxTimeMS sets a server-side time limit (pre-CSOT API) and must be a numeric millisecond value; strings, BigInt, and undefined are rejected.","triggerScenarios":"Calling maxTimeMS('5000'), maxTimeMS(BigInt(5000)), maxTimeMS(undefined), or maxTimeMS(process.env.MAX_MS) where the env var is a string. Note: when using CSOT (timeoutMS), maxTimeMS is managed automatically and should not be set.","commonSituations":"Reading the value from an env var or JSON config (always strings); mixing BigInt from a config parser; setting maxTimeMS while also using timeoutMS (the latter supersedes it).","solutions":["Coerce: maxTimeMS(Number(value)).","If using CSOT/timeoutMS, remove maxTimeMS entirely.","Validate the source is numeric before calling."],"exampleFix":"// before\ncursor.maxTimeMS(process.env.MAX_MS); // string\n// after\ncursor.maxTimeMS(Number(process.env.MAX_MS));","handlingStrategy":"validation","validationCode":"if (typeof value !== 'number') throw new TypeError('maxTimeMS must be a number');\ncursor.maxTimeMS(value);","typeGuard":"function isNumber(v): v is number { return typeof v === 'number' && !Number.isNaN(v); }","tryCatchPattern":null,"preventionTips":["Coerce env-var/config strings with Number() before passing.","Do not set maxTimeMS when using CSOT timeoutMS — let the driver manage it.","Type your config schema so timeout fields are numeric."],"tags":["cursor","timeout","type-validation","options"],"analyzedSha":"3366c21a6311e02f1be91da982f9b93d3cce99a0","analyzedAt":"2026-08-04T13:40:15.335Z","schemaVersion":2}