mongodb/node-mongodb-native · error · MongoInvalidArgumentError

Option "maxStalenessSeconds" must be at least ${SMALLEST_MAX

Error message

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

What it means

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.

Source

Thrown at src/sdam/server_selection.ts:138

  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 -
        server.lastWriteDate -
        (primary.lastUpdateTime - primary.lastWriteDate) +
        topologyDescription.heartbeatFrequencyMS;

      const staleness = stalenessMS / 1000;
      const maxStalenessSeconds = readPreference.maxStalenessSeconds ?? 0;

View on GitHub (pinned to 3366c21a63)

Solutions

1. Set `maxStalenessSeconds` to at least 90.
2. Reconsider whether staleness-based selection is the right tool; use tags or latency selection instead.
3. Document the 90s floor in your connection-string helpers to prevent recurrence.

Example fix

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

function assertMaxStaleness(value) {
  if (value != null && value < 90) throw new RangeError('maxStalenessSeconds must be >= 90');
  return value;
}

function isValidMaxStaleness(value) {
  return value == null || (Number.isInteger(value) && value >= 90);
}

When it happens

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

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

Related errors

• Option "maxStalenessSeconds" must be at least ${maxStaleness
• 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/9b4c51da35b61af0.json. Report an issue: GitHub.