Detecting inconsistent indexes across shards
Parent: Rolling index builds · Published reference · snapshot 2026-10-30
↓ Facts as markdownall context files
Source-anchored research for Detecting inconsistent indexes across shards. 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
- Percona ClusterSync counts $indexStats occurrences against the _id_ index's shard coverage. Its v1.0.0 ListInconsistentIndexes documentation explicitly excludes differing keys or options when an index exists everywhere, and skips names with no usable spec on any shard. (medium confidence) [source]
How-to and procedures
- Run db.runCommand({checkMetadataConsistency:1,checkIndexes:true}) through mongos, or db.collection.checkMetadataConsistency({checkIndexes:true}) for one collection. Index checking is opt-in. (high confidence) [source]
- Check after index operations settle: concurrent index creation, deletion, or modification can produce false positives. An empty result from the default metadata check does not establish index consistency because index checks default to disabled. (low confidence) [source]
Problems, failure modes and limitations
- Interpret deprecated-option differences separately from missing indexes: mongosync documents ignoring ns and background, while SERVER-86556 requests that metadata/index consistency checks ignore deprecated background differences. The tools therefore need not classify the same specifications identically. (medium confidence) [source]
Facts and statements
- Cross-shard index consistency requires matching indexes and options on every shard holding chunks. A missed shard or a different specification during a rolling build can leave divergence. (high confidence) [source]
- The config-server primary's serverStatus.shardedIndexConsistency reports the number of sharded collections with inconsistent indexes; it is an alerting signal that requires follow-up to locate the differences. (high confidence) [source]
- InconsistentIndex results identify the namespace and indexName, with missingFromShards for absent indexes and inconsistentProperties for divergent options, such as expireAfterSeconds. (low confidence) [source]
- A 2024 operator report describes _id_ indexes with legacy ns fields in $indexStats after a 4.4-to-6.0 upgrade, triggering periodic inconsistency warnings despite getIndexes omitting ns. This is reported experience, not a confirmed universal upgrade defect. (low confidence) [source]
- SERVER-99357 describes createIndexes/dropIndex interleavings with chunk migration that leave divergent indexes. SERVER-127043 links such divergence to blocked migrations and removeShard; its test-hook fix must not be mistaken for fixing the underlying race. (high confidence) [source]
- SERVER-94740 records a metadata-check false-positive bug caused by reading shard metadata during an active critical section; the issue lists 8.0.0 as affected and 8.0.5/8.1.0-rc0 as fixes. This scopes historical metadata results and is distinct from concurrent-index-operation warnings. (low confidence) (verified as of 2025-06-30) [source]
- Alibaba Cloud's MongoDB 7.0 release overview introduces checkMetadataConsistency as a cross-shard metadata check and recommends including it in routine maintenance. That overview alone does not establish that index checking is enabled. (low confidence) [source]
- For confirmed missing coverage, createIndex through mongos builds the absent copies. For mismatched options, the documented general repair is dropping the incorrect copy and rebuilding it; TTL expiry differences can instead use collMod. (medium confidence) [source]
Children
- Cross-shard index coverage comparison (frontier)
- Index specification normalization (frontier)
- Metadata consistency false positives (frontier)
Frontier under this node: Cross-shard index coverage comparison, Index specification normalization, Metadata consistency false positives