How to Fix MongoDB Error 11000 (DuplicateKey)

Published
Length
3 min read

Luis Felipe Dias

All posts

A write triggers mongodb error 11000 when a new document matches an existing unique index key. You fix it by updating the existing record, changing the input key, or fixing index rules. In the database engine, this failure carries the official name DuplicateKey and code 11000. The engine blocks the write right away to protect data integrity across the collection. Teams see this error during single inserts, batch writes, or document updates in live apps. What causes mongodb error 11000 in the

Your coding agents run with your access.

Claude Code reaches prod with a developer's credentials, and approval prompts get clicked through. hoop.dev checks every query, masks sensitive data, and holds risky changes for a human.

A write triggers mongodb error 11000 when a new document matches an existing unique index key. You fix it by updating the existing record, changing the input key, or fixing index rules.

In the database engine, this failure carries the official name DuplicateKey and code 11000. The engine blocks the write right away to protect data integrity across the collection. Teams see this error during single inserts, batch writes, or document updates in live apps.

What causes mongodb error 11000 in the database engine

Every collection has a built-in unique index on its primary identifier field by default. Teams also create custom unique indexes on fields like user emails or account numbers. If an app sends a document with an existing value in those fields, the write fails.

Missing fields are another common trigger for this duplicate key failure in live databases. When a document omits an indexed field, the database stores a null value in the index. A standard unique index allows only one document to have a null value for that field. The second document with a missing field triggers code 11000 right away.

Race conditions in client apps also cause duplicate key errors during peak traffic hours. Two app workers might check for a record at the same time and find nothing. Both workers then try to insert the same record at once. The first write succeeds, and the second write fails with a DuplicateKey error.

Batch imports and retry loops can also trigger this error when network links drop. If a client retries a write that already finished on the server, the second try fails. Understanding which index rejected the write is the first step toward a safe fix.

How to diagnose and fix duplicate keys in production

Start by reading the full error message in your app logs to find the index name. Next, check the collection indexes and find the conflicting document using a read-only role. MongoDB grants access through roles that apply to a database down to the collection level.

MongoDB Authentication & Authorization + End-to-End Encryption: architecture patterns and best practices

Continue reading? Get the full guide.

Free. No spam. Unsubscribe anytime.

Use the built-in read role when you investigate the problem in a live database. The read role lets you find documents and list indexes without allowing data changes. It blocks insert, update, remove, and drop actions so engineers cannot break live data by mistake. If those records hold emails, phone numbers, or card numbers, masking rewrites matched fields in results.

Once you find the root cause, pick a fix that matches your app data rules. For race conditions, switch from separate check and insert calls to an atomic upsert operation. An upsert updates the document if it exists or inserts it if it is missing.

If missing fields cause null collisions, replace the standard index with a partial or sparse index. A sparse index skips documents that do not have the indexed field at all. To change indexes or fix bad records, an engineer needs the readWrite role on that database. The readWrite role includes index creation, index removal, and document update actions.

Never drop a unique index in production just to make an urgent batch write succeed. Dropping the index allows bad data into the collection and makes cleanup much harder later. Always test your index changes and data fixes in a staging database before running them live.

Add command guardrails and field masking beside MongoDB

Collection roles and IP rules control who connects to MongoDB. Yet an active client or agent session can still run a pipeline that writes data or reads raw personal fields. In practice, hoop.dev sits inline in the wire protocol beside your database as a sidecar for your MongoDB. For every command an agent or human sends in production, hoop.dev decides to pass, mask, block, or escalate it for review.

Using hoop.dev MongoDB controls, guardrails refuse banned commands before they run or hold risky calls for approval, and data masking rewrites matched fields in returned documents in memory. Furthermore, hoop.dev holds SOC 2 Type II, is MIT licensed, and generates evidence for GDPR, HIPAA, and PCI DSS programs. View the project on GitHub.

Frequently asked questions

Why does mongodb error 11000 happen when the field is missing?

A standard unique index stores a null value when a document omits the indexed field. When a second document also omits that field, the second null value breaks the unique rule. Using a sparse or partial index tells the database to ignore documents without that field.

Which database role do I need to inspect indexes for error 11000?

You only need the built-in read role on the target database to inspect indexes and documents. This role grants actions to list indexes and find records without allowing any data changes. You will need the readWrite role later if you must drop or create an index.

How do I handle error 11000 during large batch inserts?

By default, a batch insert stops at the first duplicate key error it hits. You can configure the batch write to run in unordered mode so valid documents still insert. Your app can then log the rejected duplicate records and process them in a separate step.

The query runs. The emails stay hidden.