**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

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.