61 database data_error ai_generated true

MongoServerError: shard key not found in document. Document does not contain shard key field 'shardKeyField'

ID: database/mongodb-shard-key-missing

Also available as: JSON · Markdown · 中文
82%Fix Rate
88%Confidence
1Evidence
2024-07-18First Seen

Version Compatibility

VersionStatusIntroducedDeprecatedNotes
MongoDB 6.0 active — — —
MongoDB 7.0 active — — —
MongoDB 8.0 active — — —
pymongo 4.6 active — — —
mongosh 2.1 active — — —

Root Cause

A write operation to a sharded MongoDB collection targets a document that is missing the shard key field, which is required for routing to the correct shard.

generic

中文

对分片MongoDB集合的写操作针对一个缺少分片键字段的文档，该字段是路由到正确分片所必需的。

Official Documentation

https://www.mongodb.com/docs/manual/core/sharding-shard-key/

Workarounds

  1. 85% success Update the document to include the shard key field before the write. Example in pymongo: collection.update_one({'_id': doc_id}, {'$set': {'shardKeyField': value}}, upsert=True) 
    Update the document to include the shard key field before the write. Example in pymongo: collection.update_one({'_id': doc_id}, {'$set': {'shardKeyField': value}}, upsert=True)
  2. 80% success If the shard key is based on a hashed field, ensure all documents have that field. Use a migration script to add the field to existing documents: db.collection.updateMany({shardKeyField: {$exists: false}}, {$set: {shardKeyField: default_value}}) 
    If the shard key is based on a hashed field, ensure all documents have that field. Use a migration script to add the field to existing documents: db.collection.updateMany({shardKeyField: {$exists: false}}, {$set: {shardKeyField: default_value}})

中文步骤

  1. Update the document to include the shard key field before the write. Example in pymongo: collection.update_one({'_id': doc_id}, {'$set': {'shardKeyField': value}}, upsert=True)
  2. If the shard key is based on a hashed field, ensure all documents have that field. Use a migration script to add the field to existing documents: db.collection.updateMany({shardKeyField: {$exists: false}}, {$set: {shardKeyField: default_value}})

Dead Ends

Common approaches that don't work:

  1. Ignore the missing shard key field and retry the write operation without changes. 95% fail

    The operation will fail again because the document still lacks the required shard key field.

  2. Remove the shard key index from the collection. 90% fail

    Removing the shard key index can break sharding and cause data distribution issues; it requires re-sharding the collection.