Overload-aware remote targeting and read-preference fallback
Parent: Read Preference · Published reference · snapshot 2026-10-29
↓ Facts as markdownall context files
Source-anchored research for Overload-aware remote targeting and read-preference fallback. Run status: COMPLETED.
These notes link each claim to its source. Some citations identify archived research reports that are no longer hosted on this site. A published reference means the content is available; it does not certify independent review or accuracy.Read the editorial policy and follow the sources before relying on a claim.
How it works
- Overload retargeting is opt-in because primaryPreferred can select secondaries more often and expose applications to stale reads; secondaryPreferred can send reads to the primary more often. (high confidence) (verified as of 2026-09-20) [source]
- A PyMongo overload-retargeting test raced because secondaries were not necessarily discovered before the operation. Tests expecting a different replica-set target must establish discovery first. (low confidence) (verified as of 2026-04-15) [source]
- When enabled, mongos can retry a primaryPreferred read on an eligible secondary after a retryable SystemOverloadedError from the primary, even if the primary remains reachable. (high confidence) (verified as of 2026-10-14) [source]
- When enabled, mongos can retry a secondaryPreferred read on the primary when secondaries indicate overload. (medium confidence) (verified as of 2026-10-14) [source]
- With the server flag disabled, retries do not avoid members merely because they signaled overload and may repeatedly target such a member. (low confidence) (verified as of 2026-10-14) [source]
Problems, failure modes and limitations
- Secondary replication is asynchronous, so increased secondary routing can expose reads to replication lag; enabling overload fallback does not remove the underlying staleness risk. (medium confidence) [source]
Comparisons and alternatives
- MongoDB 8.3 also introduced retry/backoff parameters for internal server-side clients between mongos and mongod; these accompany overload retargeting but control retry pacing rather than which member is preferred. (low confidence) (verified as of 2026-10-14) [source]
Facts and statements
- MongoDB 8.3 introduced overloadAwareServerSelectionEnabled to opt into avoiding members that recently returned SystemOverloadedError during retries targeting other servers in the cluster. (high confidence) (verified as of 2026-10-14) [source]
- With overloadAwareServerSelectionEnabled=true, a router retrying a primary read that received a retryable SystemOverloadedError may choose an eligible secondary; the read-preference documentation limits this behavior to modes that can select multiple servers. (low confidence) (verified as of 2026-10-14) [source]
- Driver enableOverloadRetargeting and server overloadAwareServerSelectionEnabled are separate controls. The driver specification says sharded clients already retarget across mongos instances on retryable errors regardless of that driver setting; mongos separately controls retargeting within shards. (medium confidence) (verified as of 2026-10-27) [source]
- SystemOverloadedError identifies overload but does not by itself establish safe retryability. RetryableError provides the explicit safe-retry signal; overload retries should apply backoff with jitter. (high confidence) (verified as of 2026-10-27) [source]
- The client overload policy makes enableOverloadRetargeting an opt-in setting, separate from maxAdaptiveRetries; the C driver release notes expose both URI options. (high confidence) (verified as of 2026-10-27) [source]
- MongoDB 8.3 introduced overloadAwareServerSelectionEnabled. Its read-preference documentation states that this server control is disabled by default. (medium confidence) (verified as of 2026-10-14) [source]
- The server parameter governs overload-induced remote retries, including mongos requests to shard members and mongod remote reads during aggregation. It is not a general balancing policy for initial reads. (medium confidence) (verified as of 2026-10-14) [source]
- Alibaba Cloud documents the flag for ApsaraDB for MongoDB 8.3, but its wording that a client automatically retries against a different node is broader than MongoDB's documented server-internal, retry-eligible scope. (medium confidence) (verified as of 2026-10-27) [source]
Children
- No children recorded.