How to Fix MongoDB Error 221 (IndexModified)
You see mongodb error 221 when an index changes while a query runs. To fix this IndexModified error, stop changing indexes during peak read traffic and retry the failed query. Database teams often see this failure during live schema updates. A background job or an engineer changes an index while an app reads data. The database stops the read operation so it does not return wrong results. Understanding how index changes interact with active queries helps you keep production stable. What causes
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 see mongodb error 221 when an index changes while a query runs. To fix this IndexModified error, stop changing indexes during peak read traffic and retry the failed query.
Database teams often see this failure during live schema updates. A background job or an engineer changes an index while an app reads data. The database stops the read operation so it does not return wrong results. Understanding how index changes interact with active queries helps you keep production stable.
What causes mongodb error 221 in production
In the database engine, code 221 maps to the IndexModified error name. When a client sends a query, the query planner picks a good index. The database then opens a cursor to scan that index and read records. If another session drops or updates that index mid-scan, the cursor loses its place.
The database engine halts the operation and returns mongodb error 221 to the client. This stops the app from getting missing or duplicate rows. You will often see this error when deployment scripts run index updates alongside heavy traffic.
Loose role permissions also make this problem much more common. In this database, roles grant actions on resources down to the collection level. The built-in readWrite role includes actions like createIndex and dropIndex alongside normal data edits. If every developer or app uses readWrite, anyone can change an index during business hours.
How to diagnose and fix IndexModified failures safely
Start by checking your database logs for recent index builds or drops. Match the timestamp of the error 221 failure with index management events. You will usually find a deployment job or an ad-hoc session that altered a collection index.
For an immediate fix, have your app retry the failed read query. Once the index update finishes, the query planner picks the new index structure. A simple retry logic in your database driver handles brief index changes well.
MongoDB Authentication & Authorization + End-to-End Encryption: architecture patterns and best practices
Continue reading? Get the full guide.
Free. No spam. Unsubscribe anytime.
Next, lock down who can change indexes in your live cluster. Give routine users and read services the built-in read role instead of readWrite. The read role grants actions like find and listIndexes without allowing createIndex or dropIndex. For apps that only edit documents, build a custom role without index actions.
How to prevent index conflicts during schema updates
Schedule all index changes during low-traffic windows to avoid active cursor conflicts. Before you drop an old index, check if active queries still use it. You can run collection stats and index checks using a basic read role.
Keep human users from running direct index commands on live data without review. Require peer approval before an engineer runs a schema change in production. When you separate daily data reads from index administration, error 221 goes away.
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
What does the IndexModified message mean in database logs?
IndexModified means a query used an index that changed before the query finished. The database stops the read request and returns code 221 to protect data accuracy.
Can a read-only database user trigger error 221?
A user with the read role cannot cause the index change itself. Still, their active find queries will fail with code 221 if another user modifies the index.
Should my app retry queries after getting code 221?
Yes, retrying the read query is safe and usually works right away. The new query execution plan will use the updated index state and return clean data.
Teams that document these role rules and review logs each month catch config drift early. Clear ownership for each role keeps live systems simple to run and easy to audit across the whole team.
Related guides
In this post