{"id":"88b48331da9ca49e","repo":"mongodb/node-mongodb-native","slug":"option-maxstalenessseconds-must-be-at-least-ma","errorCode":null,"errorMessage":"Option \"maxStalenessSeconds\" must be at least ${maxStalenessVariance} seconds","messagePattern":"Option \"maxStalenessSeconds\" must be at least (.+?) seconds","errorType":"exception","errorClass":"MongoInvalidArgumentError","httpStatus":null,"severity":"error","filePath":"src/sdam/server_selection.ts","lineNumber":132,"sourceCode":" * @param readPreference - The read preference providing max staleness guidance\n * @param topologyDescription - The topology description\n * @param servers - The list of server descriptions to be reduced\n * @returns The list of servers that satisfy the requirements of max staleness\n */\nfunction maxStalenessReducer(\n  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 -","sourceCodeStart":114,"sourceCodeEnd":150,"githubUrl":"https://github.com/mongodb/node-mongodb-native/blob/3366c21a6311e02f1be91da982f9b93d3cce99a0/src/sdam/server_selection.ts#L114-L150","documentation":"Thrown by `maxStalenessReducer` during server selection when `maxStalenessSeconds` is below `maxStalenessVariance`, where variance = (heartbeatFrequencyMS + IDLE_WRITE_PERIOD) / 1000 and IDLE_WRITE_PERIOD is 10s (server_selection.ts:129). This variance represents the uncertainty window in staleness estimation; a smaller maxStaleness cannot be reliably honored.","triggerScenarios":"Setting `maxStalenessSeconds` to a small value (e.g. 5 or 15) on a read preference while reading from a replica set; the heartbeat frequency widens the variance so low values are rejected.","commonSituations":"Wanting near-real-time secondary reads and setting a tiny staleness; tuning heartbeatFrequencyMS higher which raises the variance floor; porting a config from another driver.","solutions":["Raise `maxStalenessSeconds` to at least 90 seconds (the absolute floor used by all drivers).","If you need fresher reads, prefer 'primary' or 'primaryPreferred' instead of staleness-based selection.","Lower `heartbeatFrequencyMS` only if you understand the monitoring-load tradeoff."],"exampleFix":"// before\nnew ReadPreference('secondary', null, { maxStalenessSeconds: 15 });\n// after\nnew ReadPreference('secondary', null, { maxStalenessSeconds: 90 });","handlingStrategy":"validation","validationCode":"const MIN_STALENESS = 90;\nfunction safeMaxStaleness(value) {\n  return value && value < MIN_STALENESS ? MIN_STALENESS : value;\n}","typeGuard":"function isStalenessFeasible(value, heartbeatFrequencyMS = 10000) {\n  return value >= (heartbeatFrequencyMS + 10000) / 1000 && value >= 90;\n}","tryCatchPattern":null,"preventionTips":["Treat 90 seconds as the effective minimum for maxStalenessSeconds.","Prefer primary reads when sub-minute freshness is required.","Document the variance floor for operators tuning heartbeatFrequencyMS."],"tags":["read-preference","server-selection","configuration"],"analyzedSha":"3366c21a6311e02f1be91da982f9b93d3cce99a0","analyzedAt":"2026-08-04T13:40:15.335Z","schemaVersion":2}