{"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/3366c21a6311e02f1be91da982f9b93d3cce99a0/src/sdam/server_selection.ts#L120-L156","documentation":"Thrown by `maxStalenessReducer` when `maxStalenessSeconds` passes the variance check but is below `SMALLEST_MAX_STALENESS_SECONDS` (90) (server_selection.ts:137). Per the cross-driver max-staleness spec, 90 seconds is the global minimum any driver will accept regardless of heartbeat frequency.","triggerScenarios":"Setting `maxStalenessSeconds` to a value between ~20 and 89 (above variance but below the spec floor), e.g. 60 seconds, on a secondary/nearest read preference.","commonSituations":"Migrating from a setting that worked elsewhere; trial-and-error tuning to a mid-range value; misreading the message from error 324 and picking a still-too-small number.","solutions":["Set `maxStalenessSeconds` to at least 90.","Reconsider whether staleness-based selection is the right tool; use tags or latency selection instead.","Document the 90s floor in your connection-string helpers to prevent recurrence."],"exampleFix":"// before\nnew ReadPreference('nearest', null, { maxStalenessSeconds: 60 });\n// after\nnew ReadPreference('nearest', null, { maxStalenessSeconds: 90 });","handlingStrategy":"validation","validationCode":"function assertMaxStaleness(value) {\n  if (value != null && value < 90) throw new RangeError('maxStalenessSeconds must be >= 90');\n  return value;\n}","typeGuard":"function isValidMaxStaleness(value) {\n  return value == null || (Number.isInteger(value) && value >= 90);\n}","tryCatchPattern":null,"preventionTips":["Enforce the 90s floor in config validation.","Clamp user-provided staleness up to 90 rather than rejecting silently.","Add a config schema test for the floor."],"tags":["read-preference","server-selection","configuration"],"analyzedSha":"3366c21a6311e02f1be91da982f9b93d3cce99a0","analyzedAt":"2026-08-04T13:40:15.335Z","schemaVersion":2}