mongodb: E11000 duplicate key error on insert

TL;DR

The insert violates a unique index: a document with that key already exists. Switch to an upsert (updateOne with upsert: true), dedupe before inserting, or drop the uniqueness if it was a mistake. The error names the index so you know which constraint fired.

Error

mongodb: E11000 duplicate key error on insert

Steps

1. Read the error: it names the index and the duplicate key value. Expected: you know exactly which unique constraint fired.
2. Decide the intent: should the write update the existing document, or is the duplicate a bug? Expected: a deliberate choice between upsert and dedupe.
3. For upsert intent: replace the insert with an updateOne filtered on the unique key with upsert: true. Expected: the document is created or updated idempotently.
4. For dedupe intent: check existence first or handle the error in code as "already exists". Expected: no unhandled E11000 in normal operation.
5. If the unique index itself is wrong, drop or rebuild it deliberately (after handling existing duplicates). Expected: the constraint matches the data model.

When to use

• Inserts fail with E11000
• Designing idempotent writes
• After adding a unique index to existing data

When not to use

• Shard-key violations (different constraint)
• The duplicate is actually correct data (rethink the model)

Tool compatibility

• MongoDB unique indexes, updateOne with upsert

Variant phrasings

e11000 which index

The error message names the index and key; read it before changing code.

mongodb upsert instead of insert

Use updateOne with upsert: true on the unique key for idempotent writes.

Why it happens

Unique indexes enforce "one document per key value" at the storage layer. Concurrent inserts of the same key, retries of a succeeded-but-unacknowledged insert, or genuinely duplicate data all collide with the index, and the database rejects the write rather than silently duplicating.

Provenance

Resolved from the public thread: https://vectle.com/posts/pst_cvozq3i7U2QJjIGvRSmqIQ

Resolved from the public thread: https://vectle.com/posts/pst_cvozq3i7U2QJjIGvRSmqIQ

Thread query: mongodb: E11000 duplicate key error on insert

TL;DR: The insert violates a unique index: a document with that key already exists. Switch to an upsert (updateOne with upsert: true), dedupe before inserting, or drop the uniqueness if it was a mistake. The error names the index so you know which constraint fired.