{"record":{"id":"9b4c51da35b61af0","repo":"mongodb/node-mongodb-native","slug":"option-maxstalenessseconds-must-be-at-least-sm","errorCode":null,"errorMessage":"Option \"maxStalenessSeconds\" must be at least ${SMALLEST_MAX_STALENESS_SECONDS} seconds","messagePattern":"Option \"maxStalenessSeconds\" must be at least (.+?) seconds","errorType":"exception","errorClass":"MongoInvalidArgumentError","httpStatus":null,"severity":"error","filePath":"src/sdam/server_selection.ts","lineNumber":138,"sourceCode":"  readPreference: ReadPreference,\n  topologyDescription: TopologyDescription,\n  servers: ServerDescription[]\n): ServerDescription[] {\n  if (readPreference.maxStalenessSeconds == null || readPreference.maxStalenessSeconds < 0) {\n    return servers;\n  }\n\n  const maxStaleness = readPreference.maxStalenessSeconds;\n  const maxStalenessVariance =\n    (topologyDescription.heartbeatFrequencyMS + IDLE_WRITE_PERIOD) / 1000;\n  if (maxStaleness < maxStalenessVariance) {\n    throw new MongoInvalidArgumentError(\n      `Option \"maxStalenessSeconds\" must be at least ${maxStalenessVariance} seconds`\n    );\n  }\n\n  if (maxStaleness < SMALLEST_MAX_STALENESS_SECONDS) {\n    throw new MongoInvalidArgumentError(\n      `Option \"maxStalenessSeconds\" must be at least ${SMALLEST_MAX_STALENESS_SECONDS} seconds`\n    );\n  }\n\n  if (topologyDescription.type === TopologyType.ReplicaSetWithPrimary) {\n    const primary: ServerDescription = Array.from(topologyDescription.servers.values()).filter(\n      primaryFilter\n    )[0];\n\n    return servers.filter((server: ServerDescription) => {\n      const stalenessMS =\n        server.lastUpdateTime -\n        server.lastWriteDate -\n        (primary.lastUpdateTime - primary.lastWriteDate) +\n        topologyDescription.heartbeatFrequencyMS;\n\n      const staleness = stalenessMS / 1000;\n      const maxStalenessSeconds = readPreference.maxStalenessSeconds ?? 0;","sourceCodeStart":120,"sourceCodeEnd":156,"githubUrl":"https://github.com/mongodb/node-mongodb-native/blob/dce7939f86fb283e167ad709955abedb7bf23124/src/sdam/server_selection.ts#L120-L156","documentation":"Thrown by maxStalenessReducer() (src/sdam/server_selection.ts:138) as MongoInvalidArgumentError when maxStalenessSeconds is below the absolute minimum SMALLEST_MAX_STALENESS_SECONDS (constant = 90, defined at server_selection.ts:9). This is the cross-driver spec floor: regardless of topology, maxStalenessSeconds must be >= 90.","triggerScenarios":"Setting maxStalenessSeconds to any value from 1 to 89 (the variance check at line 131 may already have rejected smaller values depending on heartbeat).","commonSituations":"Setting low staleness values based on application latency targets without knowing the 90-second spec minimum.","solutions":["Set maxStalenessSeconds to at least 90.","If 90s is too stale for your use case, reconsider whether staleness-based selection is the right mechanism."],"exampleFix":"// before\nnew ReadPreference('secondary', undefined, { maxStalenessSeconds: 60 });\n// after\nnew ReadPreference('secondary', undefined, { maxStalenessSeconds: 90 });","handlingStrategy":"validation","validationCode":"const MIN = 90;\nfunction safeMaxStaleness(v) {\n  if (v < MIN) throw new Error(`maxStalenessSeconds must be >= ${MIN}`);\n  return v;\n}","typeGuard":"function isAtLeast90(v): v is number {\n  return typeof v === 'number' && v >= 90;\n}","tryCatchPattern":"try {\n  await collection.findOne({}, { readPreference: new ReadPreference('secondary', undefined, { maxStalenessSeconds }) });\n} catch (e) {\n  if (e instanceof MongoInvalidArgumentError && /at least 90/.test(e.message)) {\n    // set to 90 and retry\n  }\n  throw e;\n}","preventionTips":["Treat 90 seconds as the hard minimum for maxStalenessSeconds across drivers.","Validate config-supplied staleness values against this floor.","Document the floor prominently in operational runbooks."],"tags":["read-preference","max-staleness","server-selection","invalid-argument"],"backgroundTag":null,"analyzedSha":"dce7939f86fb283e167ad709955abedb7bf23124","analyzedAt":"2026-08-11T04:54:53.215Z","contentChangedAt":null,"schemaVersion":2},"datasetVersion":"2026-09-23T08:17:48.524Z"}