Sharded routing-cache invalidation and stale-metadata diagnosis
Parent: MongoDB Query Shape Optimization: Sort, Pagination, Operators and Sharded Targeting · Published reference · snapshot 2026-10-29
↓ Facts as markdownall context files
Source-anchored research for Sharded routing-cache invalidation and stale-metadata diagnosis. 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.
Definitions
- The documented flushRouterConfig scopes are a collection namespace, a database and its collections, or every database and collection using a non-string scalar such as 1. The command is available on mongos and mongod and requires the flushRouterConfig privilege on the cluster resource. (low confidence) [source]
Structure and components
- Alibaba Cloud documents residual routing data after dropDatabase followed by recreation of the same database or collection name in older ApsaraDB sharded clusters. It identifies MongoDB 4.4 and earlier as affected, recommends 5.0 or later, and describes flushing all mongos as part of the older 4.2-and-earlier procedure. This guidance is scoped to its historical managed-service behavior. (low confidence) (verified as of 2026-10-27) [source]
- A March 2024 Percona forum report after logical restore contains StaleConfig code 13388, a timestamp-mismatch message, namespace, shardId, vReceived and vWanted. A reply suggests a collection-scoped flush, but the thread does not confirm that this fixed the restore problem. Preserve those diagnostic fields without promoting the suggested workaround into a verified recovery procedure. (low confidence) [source]
How it works
- When forcing router cache refresh across a deployment, address each mongos directly. The FAQ gives this instruction, and Percona reports resolving an upgrade incident by refreshing every router. (high confidence) [source]
- Routing-cache refresh is normally automatic. The current manual says an explicit flush is no longer required after movePrimary, dropDatabase, or db.collection.getShardDistribution(); its MongoDB 7.0 page still instructs a flush before getShardDistribution. Use documentation for the deployed version when applying historical runbooks. (high confidence) (verified as of 2026-10-27) [source]
- Treat cache invalidation and catalog consistency checking as separate diagnostic steps. MongoDB recommends checking metadata after major maintenance; the troubleshooting guide identifies direct config-database manipulation and writes that bypass mongos as potential origins of inconsistencies that can cause incorrect results or data loss. (high confidence) [source]
- checkMetadataConsistency, introduced in MongoDB 7.0, checks sharding metadata at cluster, database, or collection scope through mongos and returns a cursor of inconsistencies. MongoDB recommends it after major maintenance; index consistency checks require checkIndexes because they are disabled by default. (low confidence) [source]
- A Percona forum reporter on October 21, 2025 described persistent placement-version mismatch errors after a MongoDB 8.0.4 restore despite restarting mongos and reportedly running a router flush. The unresolved report supplies a counterexample to assuming that every StaleConfig symptom is fixed by flushing; it does not establish a root cause or a verified product defect. (low confidence) [source]
Problems, failure modes and limitations
- mongos caches cluster metadata and refreshes it lazily when a request to a shard reveals that the cached metadata is out of date. A stale-config warning can persist until the affected routers refresh their caches. (high confidence) [source]
- In an article published on September 26, 2024, Percona describes a customer incident during an upgrade from MongoDB 5.0 to 6.0, including the literal error "BSON field 'DatabaseVersion.timestamp' is missing but a required field". The customer had skipped a routing-cache refresh prerequisite; refreshing every mongos resolved that incident. This is a specific upgrade example, not a universal explanation for query failures. (low confidence) (verified as of 2024-09-26) [source]
- Starting in MongoDB 7.0, checkMetadataConsistency checks sharding catalog inconsistencies. The command runs through mongos and can inspect the cluster, a database, or a collection; it returns a cursor of inconsistency documents. The troubleshooting guide distinguishes these inconsistencies from the separate stale-cache warning. (high confidence) (verified as of 2026-10-14) [source]
- The serverStatus output documents shardingStatistics.countStaleConfigErrors and a shardingStatistics.catalogCache object with refresh wait time, active incremental/full refreshes, refresh-start counters and failed refreshes. These fields provide refresh-related telemetry; their existence alone does not establish that a reported application failure came from a stale router cache. (low confidence) (verified as of 2026-10-14) [source]
Comparisons and alternatives
- Alibaba Cloud's ApsaraDB guidance identifies same-name database or collection recreation after dropDatabase as a residual-routing-data risk for sharded instances running 4.4 or earlier and recommends 5.0 or later. Keep this statement scoped to that provider's guidance rather than treating its version boundary as a universal MongoDB rule. (low confidence) [source]
Facts and statements
- flushRouterConfig marks cached routing information stale; the next operation that requests that routing information refreshes the cache. A successful flush command is therefore an invalidation acknowledgement, not evidence that a subsequent read has already refreshed metadata. (high confidence) [source]
- The administrative command can target one collection with db.adminCommand({flushRouterConfig:"db.collection"}), one database and its collections with {flushRouterConfig:"db"}, or all databases with {flushRouterConfig:1}; the documented command is available on mongos and mongod. (high confidence) [source]
- SERVER-122427 describes a database-routing refresh convoy after movePrimary or database drop and recreation: stale-database responses without a wanted version could repeatedly invalidate the cache, making refresh work depend on concurrency interleavings. The issue explains why multiple stale requests need not collapse into one refresh; it is not evidence that all releases have the same defect. (low confidence) (verified as of 2026-09-20) [source]
- The flushRouterConfig command requires the flushRouterConfig privilege action on the cluster resource; the current manual lists clusterManager and hostManager among roles granting that action. (low confidence) (verified as of 2026-10-14) [source]
- An informational StaleConfig log can be a normal consequence of balancing. In MongoDB's November 2021 example, the received and wanted versions differed and the next log recorded successful automatic refresh; that sequence required no manual action. (medium confidence) [source]
- Diagnostic inference: correlate the namespace, vReceived, vWanted, shard identity, subsequent refresh messages, and whether the application still fails. A stale-version log followed by successful refresh has a different significance from repeated application errors after an attempted refresh. (medium confidence) [source]
- Diagnostic inference: cache invalidation and metadata consistency checking answer different questions. Use flushRouterConfig to invalidate routing caches and checkMetadataConsistency to inspect catalog inconsistencies; neither a successful flush nor ok:1 alone demonstrates absence of catalog inconsistency results. (medium confidence) [source]
Children
- Routing refresh concurrency and invalidation convoys (frontier)
- Catalog consistency after restore or database recreation (frontier)
Frontier under this node: Catalog consistency after restore or database recreation, Routing refresh concurrency and invalidation convoys