{"record":{"id":"b716dce0b2f449e8","repo":"mongodb/node-mongodb-native","slug":"maxstalenessseconds-must-be-a-positive-integer","errorCode":null,"errorMessage":"maxStalenessSeconds must be a positive integer","messagePattern":"maxStalenessSeconds must be a positive integer","errorType":"exception","errorClass":"MongoInvalidArgumentError","httpStatus":null,"severity":"error","filePath":"src/read_preference.ts","lineNumber":103,"sourceCode":"    if (!ReadPreference.isValid(mode)) {\n      throw new MongoInvalidArgumentError(`Invalid read preference mode ${JSON.stringify(mode)}`);\n    }\n    if (options == null && typeof tags === 'object' && !Array.isArray(tags)) {\n      options = tags;\n      tags = undefined;\n    } else if (tags && !Array.isArray(tags)) {\n      throw new MongoInvalidArgumentError('ReadPreference tags must be an array');\n    }\n\n    this.mode = mode;\n    this.tags = tags;\n    this.hedge = options?.hedge;\n    this.maxStalenessSeconds = undefined;\n\n    options = options ?? {};\n    if (options.maxStalenessSeconds != null) {\n      if (options.maxStalenessSeconds <= 0) {\n        throw new MongoInvalidArgumentError('maxStalenessSeconds must be a positive integer');\n      }\n\n      this.maxStalenessSeconds = options.maxStalenessSeconds;\n    }\n\n    if (this.mode === ReadPreference.PRIMARY) {\n      if (this.tags && Array.isArray(this.tags) && this.tags.length > 0) {\n        throw new MongoInvalidArgumentError('Primary read preference cannot be combined with tags');\n      }\n\n      if (this.maxStalenessSeconds) {\n        throw new MongoInvalidArgumentError(\n          'Primary read preference cannot be combined with maxStalenessSeconds'\n        );\n      }\n\n      if (this.hedge) {\n        throw new MongoInvalidArgumentError(","sourceCodeStart":85,"sourceCodeEnd":121,"githubUrl":"https://github.com/mongodb/node-mongodb-native/blob/dce7939f86fb283e167ad709955abedb7bf23124/src/read_preference.ts#L85-L121","documentation":"Thrown by the ReadPreference constructor (src/read_preference.ts:103) when options.maxStalenessSeconds is present but <= 0. The driver requires a positive integer for staleness-based secondary reads. Surfaces as MongoInvalidArgumentError.","triggerScenarios":"Passing maxStalenessSeconds: 0, a negative number, or NaN (e.g. from a bad config parse) in ReadPreference options or via MongoClient URI ?maxStalenessSeconds=0.","commonSituations":"Treating 0 as 'disabled' (the driver treats 0 as invalid — omit the option instead), off-by-one in config, or unguarded user input.","solutions":["Omit maxStalenessSeconds entirely if you do not want staleness limiting.","Set it to a positive integer (minimum 90 seconds — see error 336).","Validate config-supplied values before passing them to the driver."],"exampleFix":"// before\nconst rp = new ReadPreference('secondary', undefined, { maxStalenessSeconds: 0 });\n// after\nconst rp = new ReadPreference('secondary', undefined, { maxStalenessSeconds: 90 });","handlingStrategy":"validation","validationCode":"function safeMaxStaleness(v) {\n  if (v == null) return undefined;\n  if (!Number.isInteger(v) || v <= 0) throw new Error('maxStalenessSeconds must be positive');\n  return v;\n}","typeGuard":"function isPositiveInt(v): v is number {\n  return typeof v === 'number' && Number.isInteger(v) && v > 0;\n}","tryCatchPattern":"try {\n  new ReadPreference('secondary', undefined, { maxStalenessSeconds });\n} catch (e) {\n  if (e instanceof MongoInvalidArgumentError && /positive integer/.test(e.message)) {\n    // drop the option or set a valid value\n  }\n  throw e;\n}","preventionTips":["Treat 0/null as 'omit the option', not as a sentinel value.","Validate numeric config before passing it through.","Remember the effective floor is 90 seconds."],"tags":["read-preference","validation","max-staleness","invalid-argument"],"backgroundTag":null,"analyzedSha":"dce7939f86fb283e167ad709955abedb7bf23124","analyzedAt":"2026-08-11T04:54:53.215Z","contentChangedAt":null,"schemaVersion":2},"datasetVersion":"2026-09-23T08:17:48.524Z"}