How to Fix MongoDB Error 640570 (IllegalChangeToExpectedShardVersion)
You see mongodb error 640570 when a shard detects an invalid change to its expected version. You fix it by refreshing your router cache and checking active chunk migrations. MongoDB names this failure IllegalChangeToExpectedShardVersion in the server logs. It happens inside sharded clusters when routing tables lose sync during heavy workloads. Teams must resolve this version conflict without giving out broad admin rights. What causes mongodb error 640570 in sharded clusters Sharded clusters
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 640570 when a shard detects an invalid change to its expected version. You fix it by refreshing your router cache and checking active chunk migrations.
MongoDB names this failure IllegalChangeToExpectedShardVersion in the server logs. It happens inside sharded clusters when routing tables lose sync during heavy workloads. Teams must resolve this version conflict without giving out broad admin rights.
What causes mongodb error 640570 in sharded clusters
Sharded clusters split large data sets across multiple servers. Query routers track which shard holds each piece of data. They use a shard version number to keep this map accurate.
Every time a router talks to a shard, it sends the expected shard version. If the version changes in an invalid way during a request, the shard stops. It then returns mongodb error 640570 to protect your data.
This mismatch often happens during chunk moves or collection drops. A network delay can also cause routers to hold old metadata. When a second operation changes the expected version mid-flight, the shard rejects the call.
Multi-document transactions across shards are another common trigger for this code. Every step in a transaction must see the exact same shard version. If a background task updates the shard map during the transaction, the request fails.
How to diagnose and fix the failure in production
Start by checking your router and shard logs for recent chunk moves. Look for collection drops or renames that happened at the exact same time. These events show why the version number shifted during the query.
You can fix the state by refreshing the router metadata cache. This step forces the router to fetch the latest map from the config servers. Once the router has the right version, new queries will succeed.
MongoDB Authentication & Authorization + End-to-End Encryption: architecture patterns and best practices
Continue reading? Get the full guide.
Free. No spam. Unsubscribe anytime.
Do not give engineers full cluster admin rights just to inspect this error. MongoDB grants access through role-based rules down to the collection level. You should give responders the built-in read role on the target database instead.
The read role lets users run find, listCollections, listIndexes, dbStats, and collStats. It does not allow insert, update, remove, or dropCollection actions. This keeps your production data safe while the team checks the cluster state.
Keep in mind that MongoDB Atlas users have different built-in roles than self-hosted users. Both deployment types build their roles from the same basic privilege actions. Always pick the smallest role that lets your team view the shard state.
How to prevent shard version conflicts
You can stop this error from coming back by scheduling schema changes during quiet hours. Dropping or recreating sharded collections during peak traffic causes version mismatches. Run these heavy tasks when user traffic is low.
Make sure all your query routers run the exact same server version. Mixed versions in a cluster can cause routers and shards to disagree on metadata rules. Keep your app drivers updated so they retry failed reads and writes.
When engineers inspect production data during an incident, protect sensitive fields. Masking rewrites matched fields like emails, phone numbers, card numbers, and national IDs in results. This lets your team debug shard issues safely.
Check MongoDB commands and documents on the wire
MongoDB roles and SCRAM login decide who opens a session. They do not check single commands or redact sensitive fields inside returned documents. With hoop.dev, you run an open-source proxy, a sidecar for your MongoDB, inline in the MongoDB wire protocol. On every command an AI agent or engineer runs against production, hoop.dev decides to pass, mask, block, or hold it for human review.
Before a command runs, hoop.dev guardrails check its effect and refuse banned drops or writes with MongoDB error code 13, or hold risky commands for approval. On the way back, hoop.dev data masking rewrites sensitive fields in returned documents in memory, and every verdict is logged. See the open-source code on GitHub.
Frequently asked questions
What does IllegalChangeToExpectedShardVersion mean in MongoDB?
It means a shard noticed its expected shard version changed mid-operation. The shard blocks the request so it does not read or write on the wrong node.
Does mongodb error 640570 cause data loss?
No, this error stops the query before it can corrupt any data. The database aborts the operation to keep your sharded collections safe and consistent.
Which role should engineers use to inspect affected collections?
Assign the built-in read role on the affected database. It allows collection stats and index checks while blocking data edits and collection drops.
Related guides
In this post