How to Fix MongoDB Error 66 (ImmutableField)

Published
Length
3 min read

Luis Felipe Dias

All posts

You get mongodb error 66 when an update command tries to change an immutable field. You fix it by removing the protected key from your update payload or replacing the record. In the database engine, code 66 maps to the ImmutableField failure state. The database blocks the write operation to protect core document identifiers and shard routing keys. Understanding why this happens helps your team fix broken writes fast. What triggers mongodb error 66 in your database Every document in a collect

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.

You get mongodb error 66 when an update command tries to change an immutable field. You fix it by removing the protected key from your update payload or replacing the record.

In the database engine, code 66 maps to the ImmutableField failure state. The database blocks the write operation to protect core document identifiers and shard routing keys. Understanding why this happens helps your team fix broken writes fast.

What triggers mongodb error 66 in your database

Every document in a collection has a primary identifier field. Once the database writes a document, that identifier cannot change. If an app sends an update that alters this key, the engine rejects the write. It returns code 66 with the ImmutableField error name.

This failure often happens when an app sends a full object back to the database. If the in-memory object has a new or blank identifier, the update fails. Upsert commands can also trigger this bug when query filters clash with the update data.

Sharded clusters add another cause for this error. The database uses shard keys to route documents to the right nodes. In many cases, the engine treats shard keys as immutable fields during normal updates. If a client tries to edit a locked shard key, the cluster stops the request.

Client drivers and object mappers can also cause this problem by mistake. Some tools copy all fields from a form into an update payload. When that payload includes an altered primary key, the database rejects the command right away.

How to diagnose and fix the failure in production

Start by checking your app logs to find the exact collection and update query. Look at the payload your app sends to the database. Check if the payload includes the document identifier or a shard key inside the update block.

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

Continue reading? Get the full guide.

Free. No spam. Unsubscribe anytime.

If your app only needs to change standard data fields, strip the identifier first. Use the primary key in the query filter to find the record. Keep that key out of the field change list. If your update sends the exact same identifier value, the engine usually ignores it. The error only fires when the new value differs from the stored value.

Sometimes you really need to change a primary identifier on an existing record. Because the field is locked, you cannot use a standard update command. Instead, your app must read the old document and copy its data into memory. Next, assign the new identifier and insert the record as a brand new document. After the insert succeeds, remove the old document from the collection.

When you inspect production data to debug this error, keep access tight. MongoDB grants access through role-based rules that apply to a single database. A role can grant access down to the collection level. Give engineers the built-in read role when they inspect records to debug code 66. The read role allows find and collection stats actions without allowing update or remove actions.

Reserve write roles for the service accounts or approved scripts that fix the data. A write role adds insert, update, and remove actions on top of read privileges. Keeping human debug sessions read-only prevents accidental changes to live keys while your team investigates. You can also apply data masking so queries rewrite emails or card numbers in results.

Inspect MongoDB wire traffic in flight

Built-in MongoDB roles govern collection access at setup time. They cannot score command risk per call or mask sensitive document values on the fly. By design, hoop.dev sits inline in the MongoDB protocol next to your server as a sidecar for your MongoDB. On every production command from mongosh, drivers, or AI agents, hoop.dev decides whether to pass, mask, block, or hold it for human review.

First, hoop.dev guardrails block bad deletes, drops, and write pipelines or hold them for approval. Next, hoop.dev data masking rewrites sensitive values in returned documents in memory and logs each decision. Explore the repo on GitHub.

Frequently asked questions

Can I bypass the ImmutableField check by using an admin role?

No, database roles control which actions a user can run on a resource. Even with full write privileges, the storage engine blocks updates to immutable fields like the primary key.

How do I fix mongodb error 66 when migrating a document to a new ID?

Read the existing document into your app and set the new identifier value. Insert that object as a new document, and then delete the original document.

Why does my upsert command throw code 66 on a second run?

On the first run, the upsert inserts a new document with your chosen identifier. On the second run, it matches the existing record and fails if the payload alters that identifier.

The query runs. The emails stay hidden.