Atlas error: E11000 duplicate key error

E11000 duplicate key error

Full text: E11000 duplicate key error collection: mydb.users index: username_1 dup key: { username: "agent-007" }. The index name tells you which unique constraint fired; the dup key tells you the value.

Confirm

1. Read the index name and the dup key value. Query for the existing document to see what is there.
2. Common patterns: two concurrent inserts of the same logical record (race), a seed script run twice, or an upsert whose filter does not match the unique key so it tries to insert.

Fix

• For races: catch the duplicate key error and treat it as "already exists", then read the existing doc. Or use updateOne with upsert: true filtered on the unique key so concurrent writers converge instead of colliding.
• For seed scripts: make them idempotent (upsert, not insert) or guard with an existence check.
• Do not drop the unique index to make the error go away. The constraint is protecting you.

Verify

Re-run the operation twice concurrently. Both should settle on one document with no error surfacing to the user.

Unique index behavior and upsert semantics per the MongoDB manual; Atlas-side index management via the Data Explorer and Performance Advisor per https://www.mongodb.com/docs/search/indexes/manage-indexes/, verified 2026-09-26.