Disallow compound wildcard indexes from being used as a shard key index

XMLWordPrintableJSON

    • Catalog and Routing
    • Fully Compatible
    • ALL
    • v8.2, v8.0, v7.0
    • CAR Team 2025-09-01, CAR Team 2025-09-15, CAR Team 2025-09-29
    • đŸŸ„ DDL
    • None
    • None
    • None
    • None
    • None
    • None

      Issue Status as of March 17, 2026

      ISSUE DESCRIPTION AND IMPACT
      Compound wildcard indexes prefixed with the shard key can be incorrectly used as a shard key index to determine which documents to move during chunk migrations, causing some documents to be left behind on the donor shard and resulting in data loss.

      When a chunk migration uses a compound wildcard index as a shard key index, all documents that are missing all of the fields covered by that index will remain on the donor shard and won’t be migrated.
      If, instead, the compound wildcard index is defined with a descending wildcard field (for example, {skey: 1, “a.$**”: -1}), the chunk migration also leaves behind documents whose shard key is equal to the chunk’s min boundary.

      Independently, if the range deleter uses a compound wildcard index as a shard key index, all the documents lacking all index fields won’t get removed, leaving dangling orphans on the donor shard.

      DIAGNOSIS AND AFFECTED VERSIONS
      Sharded collections with compound wildcard indexes prefixed with the shard key may be affected on versions MongoDB 7.0.0-7.0.30, MongoDB 8.0.0-8.0.17, and MongoDB 8.2.0-8.2.1.

      A sharded cluster may have been impacted by this issue if all of the following conditions are true (now or at any point in the past) for a sharded collection:

      1. Your sharded cluster has two or more shards;
      2. The collection has a compound wildcard index where the shard key appears first in the index definition—for example, if your shard key is {skey: 1}, an affected index would look like {skey: 1, "a.$**": 1} (the $** indicates a wildcard component);
      3. The balancer was active for that collection, or chunks were moved manually; and
      4. Either:
        • The collection contains documents missing all fields defined in the compound wildcard index, or
        • The compound wildcard index is in descending order (e.g., {skey: 1,  “a.$**”: -1})

      The following steps explain how to verify that a sharded collection has a compound wildcard index prefixed with the shard key:

      1. List the collection’s indexes and review their key patterns. In mongosh, run the following to list all indexes for that collection: db.getSiblingDB("<db>").getCollection("<collection>").getIndexes().
      2. Identify compound wildcard indexes: look for an index key that includes $** plus at least one additional field (for example, {skey: 1, "a.$**": 1}).
      3. Confirm the shard key prefix: the shard key field(s) must appear first in the index key pattern, in the same order as the shard key.
      4. If these conditions are met, the index is a compound wildcard index prefixed with the shard key.

      REMEDIATION AND WORKAROUNDS

      • Upgrade to a fixed version and keep the balancer disabled until all the remediation steps are completed. The fixed versions are MongoDB 7.0.31+ (i.e., any 7.0.Y that includes the fix), 8.0.18+, or 8.2.2+.
      • If dangling orphans are suspected (e.g., due to prior migrations using a compound wildcard index), use the provided remediation procedures/scripts to detect, recover, and clean up dangling orphans. Note that newer versions may surface such cases during chunk migrations due to SERVER-110953.
      • Because this fix removes compound wildcard indexes from the set of indexes that can support a shard key, some sharded collections might no longer have a valid shard key index after upgrade. Therefore, you’ll need to verify that every sharded collection has a valid shard key index. If a collection reports a MissingShardKeyIndex in the checkMetadataConsistency command, you’ll need to create a valid shard key index via a mongos connection. Additionally, if range deletions are blocked on shards that do not own chunks (log message 23765 “Unable to find range shard key index”), create the shard key index through direct shard connections on those shards to unblock the range deleter.
      • Finally, re-enable the balancer if it was enabled before the upgrade.

      Interim workarounds if you cannot upgrade immediately, you can either:

      • Disable the balancer at the cluster level and stop the range deleter on every node in the cluster by setting the `disableResumableRangeDeleter` server parameter to ‘true’ for all sharded collections that have a compound wildcard index prefixed with the shard key, OR
      • Drop all the compound wildcard indexes that are prefixed with the shard key.

            Assignee:
            Silvia Surroca
            Reporter:
            Matt Boros
            Votes:
            0 Vote for this issue
            Watchers:
            27 Start watching this issue

              Created:
              Updated:
              Resolved: