MongoDB Unique Key Collision: Concurrency Races, Upsert Race Conditions & Idempotent Write Patterns
Diagnosing E11000 errors caused by concurrent insert races, index verification, and implementing atomic upsert with $setOnInsert.
Operational Verification & Reliability Metadata
The error string is a symptom, not the root cause. Do not restart the server blindly. Run the diagnostic queries below to pinpoint the actual failure mode.
▸Symptom
Document insertions fail with unique index violation:
MongoServerError: E11000 duplicate key error collection: prod.users index: email_1 dup key: { email: "a@b.com" }▸What You See in Production
Parallel registration requests or concurrent worker threads collide during write operations.
▸Root Cause Matrix
| Probability | Root Cause | Description |
|---|---|---|
| %65 | Concurrent Race Conditions | Two threads check existence with findOne, then both attempt insertOne. |
| %25 | Batch Insert Default (`ordered: true`) | A single duplicate halts entire insertMany batch execution. |
| %10 | Null Value Key Collisions | Multiple missing fields indexed as duplicate null values. |
▸EMERGENCY RUNBOOK (0-5 min)
// 1. Inspect existing duplicate record
db.users.find({ email: "a@b.com" });
// 2. Implement atomic upsert
db.users.updateOne(
{ email: "a@b.com" },
{
$set: { last_login: new Date() },
$setOnInsert: { created_at: new Date(), name: "Ali" }
},
{ upsert: true }
);
// 3. Unordered batch insertions
db.users.insertMany(docs, { ordered: false });▸PERMANENT BLUEPRINT
- 1Atomic Upsert Logic: Replace read-then-write chains with atomic upserts.
- 2Sparse Indexes: Prevent null collisions with sparse or partial filter expressions.
▸Verification
db.users.getIndexes().filter(idx => idx.unique);Other Database Error Triage Playbooks
Other battle-tested diagnostic guides for high-severity database errors.
MongoDB "not master" / NotWritablePrimary Fix
Troubleshooting MongoDB "not master" (legacy < 5.0) and NotWritablePrimary (code 10107 >= 5.0) during replica set failovers, connection string topology URIs, retryWrites, and oplog sizing.
MongoDB MongoNetworkError & HostUnreachable Triage
Addressing driver network timeouts, topology change failovers, invalid SRV connection strings, and serverSelectionTimeoutMS tuning.
MongoDB WriteConcernFailed & wtimeout Triage
Troubleshooting write concern timeouts when quorum majority cannot be satisfied due to lagging or unreachable secondary nodes.