📋

Description

MongoDB Error 11000, 'Duplicate Key', indicates that a write operation (insert or update) attempted to create or modify a document in a way that violates a unique index constraint. This typically happens when trying to store a document with a value for an indexed field that already exists for another document in the collection, where that index is marked as unique.

💬

Error Message

Duplicate Key

🔍

Known Causes

4 known causes

⚠️

Duplicate `_id` Field Insertion

This occurs when trying to insert a new document with an `_id` value that already exists in the collection, violating the default unique `_id` index.

⚠️

Custom Unique Index Violation

An attempt was made to insert or update a document that results in a duplicate value for a field covered by a user-defined unique index.

⚠️

Incorrect Upsert Operation

An upsert operation (update with `upsert: true`) tried to create a new document or modify an existing one, causing a unique index violation.

⚠️

Concurrent Write Conflict

Multiple concurrent write operations attempted to insert or update documents with the same unique key value, leading to one succeeding and others failing.

🛠️

Solutions

5 solutions available

1. Use updateOne with upsert easy

Update if exists, insert if not

1

Upsert pattern

db.users.updateOne(
  { email: "test@example.com" },
  { $set: { name: "John", email: "test@example.com" } },
  { upsert: true }
);

2. Use findOneAndUpdate easy

Atomic find and update/insert

1

Find and update or insert

db.users.findOneAndUpdate(
  { email: "test@example.com" },
  { $setOnInsert: { createdAt: new Date() }, $set: { name: "John" } },
  { upsert: true, returnNewDocument: true }
);

3. Handle in Application Code easy

Catch and handle duplicate key error

1

Node.js/Mongoose example

try {
  await User.create({ email: 'test@example.com', name: 'John' });
} catch (err) {
  if (err.code === 11000) {
    // Handle duplicate
    console.log('Email already exists');
    // Maybe update instead
    await User.updateOne({ email: 'test@example.com' }, { name: 'John' });
  } else {
    throw err;
  }
}

2

Python/PyMongo example

from pymongo.errors import DuplicateKeyError

try:
    collection.insert_one({'email': 'test@example.com', 'name': 'John'})
except DuplicateKeyError:
    collection.update_one(
        {'email': 'test@example.com'},
        {'$set': {'name': 'John'}}
    )

4. Find and Remove Duplicates medium

Clean up existing duplicate data

1

Find duplicates

db.users.aggregate([
  { $group: { _id: "$email", count: { $sum: 1 }, docs: { $push: "$_id" } } },
  { $match: { count: { $gt: 1 } } }
]);

2

Remove duplicates keeping first

db.users.aggregate([
  { $group: { _id: "$email", count: { $sum: 1 }, docs: { $push: "$_id" } } },
  { $match: { count: { $gt: 1 } } }
]).forEach(function(doc) {
  doc.docs.shift();  // Keep first
  db.users.deleteMany({ _id: { $in: doc.docs } });
});

5. Use Bulk Write with Ordered False medium

Continue on duplicate errors in bulk operations

1

Unordered bulk write

db.users.bulkWrite(
  [
    { insertOne: { document: { email: 'a@test.com' } } },
    { insertOne: { document: { email: 'b@test.com' } } },
    { insertOne: { document: { email: 'a@test.com' } } }  // Duplicate
  ],
  { ordered: false }  // Continue on error
);

🔗

Related Errors

5 related errors

MongoDB Error 11000: Duplicate Key Violation