mongodb/node-mongodb-native · error · MongoInvalidArgumentError

Option "maxStalenessSeconds" must be at least ${maxStaleness

Error message

Option "maxStalenessSeconds" must be at least ${maxStalenessVariance} seconds

What it means

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.

Source

Thrown at src/sdam/server_selection.ts:132

 * @param readPreference - The read preference providing max staleness guidance
 * @param topologyDescription - The topology description
 * @param servers - The list of server descriptions to be reduced
 * @returns The list of servers that satisfy the requirements of max staleness
 */
function maxStalenessReducer(
  readPreference: ReadPreference,
  topologyDescription: TopologyDescription,
  servers: ServerDescription[]
): ServerDescription[] {
  if (readPreference.maxStalenessSeconds == null || readPreference.maxStalenessSeconds < 0) {
    return servers;
  }

  const maxStaleness = readPreference.maxStalenessSeconds;
  const maxStalenessVariance =
    (topologyDescription.heartbeatFrequencyMS + IDLE_WRITE_PERIOD) / 1000;
  if (maxStaleness < maxStalenessVariance) {
    throw new MongoInvalidArgumentError(
      `Option "maxStalenessSeconds" must be at least ${maxStalenessVariance} seconds`
    );
  }

  if (maxStaleness < SMALLEST_MAX_STALENESS_SECONDS) {
    throw new MongoInvalidArgumentError(
      `Option "maxStalenessSeconds" must be at least ${SMALLEST_MAX_STALENESS_SECONDS} seconds`
    );
  }

  if (topologyDescription.type === TopologyType.ReplicaSetWithPrimary) {
    const primary: ServerDescription = Array.from(topologyDescription.servers.values()).filter(
      primaryFilter
    )[0];

    return servers.filter((server: ServerDescription) => {
      const stalenessMS =
        server.lastUpdateTime -

View on GitHub (pinned to 3366c21a63)

Solutions

1. Raise `maxStalenessSeconds` to at least 90 seconds (the absolute floor used by all drivers).
2. If you need fresher reads, prefer 'primary' or 'primaryPreferred' instead of staleness-based selection.
3. Lower `heartbeatFrequencyMS` only if you understand the monitoring-load tradeoff.

Example fix

// before
new ReadPreference('secondary', null, { maxStalenessSeconds: 15 });
// after
new ReadPreference('secondary', null, { maxStalenessSeconds: 90 });

const MIN_STALENESS = 90;
function safeMaxStaleness(value) {
  return value && value < MIN_STALENESS ? MIN_STALENESS : value;
}

function isStalenessFeasible(value, heartbeatFrequencyMS = 10000) {
  return value >= (heartbeatFrequencyMS + 10000) / 1000 && value >= 90;
}

When it happens

Trigger: 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.

Common situations: 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.

Related errors

• Option "maxStalenessSeconds" must be at least ${SMALLEST_MAX
• Option "readPreference" must be a ReadPreference instance
• Cannot make read preference from ${JSON.stringify(value)}
• Unknown ReadPreference value: ${value}
• Primary read preference cannot be combined with hedge

AI-assisted analysis of mongodb/node-mongodb-native@3366c21a63 (2026-08-04). Data as JSON: /data/errors/88b48331da9ca49e.json. Report an issue: GitHub.