Sharding catalog consistency checks beyond index parity
Parent: Shard Key Design and Resharding as Cost Levers · Published reference · snapshot 2026-10-29
↓ Facts as markdownall context files
Source-anchored research for Sharding catalog consistency checks beyond index parity. 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
- SERVER-130709 documents AuthoritativeShardCatalogCollectionsPresent false positives when checkMetadataConsistency overlaps setFCV: the issue affects 9.0.0-rc0 and lists a fix in 9.0.0-rc1. This is a release-specific race, not proof that every reported catalog mismatch is harmless. (low confidence) (verified as of 2026-07-14) [source]
- SERVER-134805 reports that corrupted database metadata on its primary shard can make cluster-level checking silently skip that database when a dbVersion check fails. A database-level invocation instead fails with StaleDbVersion. The ticket lists no affected versions, so the report does not establish which production releases exhibit this behavior. (low confidence) (verified as of 2026-10-16) [source]
Problems, failure modes and limitations
- Operational inference: include catalog consistency checks in maintenance acceptance criteria to expose latent metadata defects, but do not assign a dollar saving or assume a clean scan proves every database was checked. The sources provide operational guidance and a coverage failure report, not a measured cost-reduction study. (medium confidence) [source]
Comparisons and alternatives
- The command runs through mongos. Use db.adminCommand({checkMetadataConsistency:1}) for cluster scope, db.runCommand({checkMetadataConsistency:1}) in the target database for database scope, or a collection name instead of 1 for collection scope. (medium confidence) [source]
- Inspect inconsistency documents rather than treating ok:1 as a clean bill of health: the documented successful result contains a MisplacedCollection finding. Consume subsequent getMore batches whenever cursor.id is nonzero. (low confidence) [source]
- SERVER-134194 reports false MissingDatabaseMetadataInShardCatalog results when a lagged secondary local catalog read is compared with fresh global metadata during DDL. The ticket identifies internal secondary check modes and lists no affected release; it does not establish that all production checks have this behavior. (low confidence) (verified as of 2026-09-18) [source]
Facts and statements
- MongoDB recommends checkMetadataConsistency after major maintenance such as upgrades and downgrades. Percona recommends checks after FCV-related maintenance and regularly; Alibaba Cloud recommends including the check in routine operations and maintenance. (high confidence) [source]
- Catalog consistency extends beyond index parity: documented checks include collection UUID mismatches and overlapping routing ranges. Percona identifies these as operational metadata problems that may remain silent until a particular operation exposes them. (medium confidence) [source]
- Index checking is optional: checkMetadataConsistency does not check indexes by default; checkIndexes:true adds index checks to the metadata checks. A run without that option still serves the non-index catalog verification scope. (medium confidence) [source]
- The documented non-index inconsistency types include missing local collections, missing routing tables, misplaced unsharded collections, routing gaps or overlaps, chunk or zone boundaries inconsistent with the shard key, and overlapping zones. These are distinct catalog or placement checks. (low confidence) [source]
- The documented non-index check set varies by release: CollectionOptionsMismatch is listed for 8.0 and backported to 7.0.23; MissingLocalCollection is listed for 8.0; CollectionAuxiliaryMetadataMismatch is listed for 8.1. Match findings and expected coverage to the deployed version. (low confidence) (verified as of 2026-10-14) [source]
- SERVER-124268 describes a test-only false positive from comparing separate $listCatalog observations while collMod changes validator metadata between them. The report explicitly states no user impact; it should not be presented as a production checkMetadataConsistency incident. (low confidence) (verified as of 2026-06-16) [source]
- MongoDB introduced checkMetadataConsistency in 7.0 for sharding metadata checks. Index parity is optional and disabled by default, so catalog checking is a distinct maintenance capability. (high confidence) [source]
- Non-index findings include CollectionUUIDMismatch between a shard and config.collections, missing routing tables, gaps or overlaps between chunk ranges, malformed chunk or zone boundary keys, and overlapping zones. (medium confidence) [source]
Children
- No children recorded.