Atlas error: E11000 duplicate key error

TL;DR: A unique index rejected the write. Usually an upsert race or a re-seed, not a broken index. Read the index name and the dup key value. Query for the existing document to see what is there.

The error

text
E11000 duplicate key error collection: mydb.users index: username_1 dup key - { username: "agent-007" }

The fix

TL;DR: A unique index rejected the write. Usually an upsert race or a re-seed, not a broken index. Read the index name and the dup key value. Query for the existing document to see what is there.

The error

E11000 duplicate key error collection: mydb.users index: username_1 dup key - { username: "agent-007" }

The fix

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.
3. 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.
4. For seed scripts: make them idempotent (upsert, not insert) or guard with an existence check.
5. Do not drop the unique index to make the error go away. The constraint is protecting you.

When to use this

• You are seeing this exact error message; match the block above, not just part of it.
• The failing call matches the scenario in the title: Atlas error.
• You want the fastest verified fix before digging through logs.

When not to use this

• Your error text differs from the block above; close cousins often have different causes.
• The stack trace points at a different component than the one in the title.
• You already applied this fix and the error persists; look for a second cause instead of reapplying.

Compatibility

• Not pinned to a specific version; follows current Atlas behavior.

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.