How to Fix MongoDB Error 105 (IncompatibleShardingMetadata)
You see mongodb error 105 when sharding metadata does not match across cluster nodes. You fix this IncompatibleShardingMetadata failure by refreshing the routing cache on your cluster. Sharded clusters split data across many servers. Each router and shard keeps a local copy of the chunk map. When these maps clash during a read or write, the database stops the query. It returns code 105 to protect your data from going to the wrong shard. Root causes of mongodb error 105 in sharded clusters Th
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 105 when sharding metadata does not match across cluster nodes. You fix this IncompatibleShardingMetadata failure by refreshing the routing cache on your cluster.
Sharded clusters split data across many servers. Each router and shard keeps a local copy of the chunk map. When these maps clash during a read or write, the database stops the query. It returns code 105 to protect your data from going to the wrong shard.
Root causes of mongodb error 105 in sharded clusters
The official name for mongodb error 105 is IncompatibleShardingMetadata. It happens when a shard or router holds old or conflicting version data. The cluster uses metadata versions to track where each data chunk lives.
Chunk moves are a common trigger for this error. When the balancer moves a chunk, it updates the config servers first. If a network drop delays the update to a router, the router sends bad metadata. The receiving shard compares its local version against the incoming query version. When the two versions conflict in an unsafe way, the shard rejects the request.
Manual changes to system collections also cause this problem. If an engineer edits config data by hand, nodes fall out of sync. Dropping and remaking a collection with the same name can also confuse routers. One router might remember the old sharding key while another sees the new one. Restoring a backup from a different cluster without clearing router caches will trigger code 105 too.
How to diagnose and fix the failure in production
Start by checking your server logs to find which collection and shard threw the error. You do not need full admin rights to inspect basic cluster state. MongoDB grants access through roles that define allowed actions on specific resources. A role applies to its target database and can control access down to one collection.
For initial checks, use an account with the built-in read role on the target database. The read role allows safe inspection actions like find, listCollections, listIndexes, dbStats, and collStats. It blocks data changes like insert, update, remove, or dropCollection. This lets your team check collection stats without risking accidental edits during an outage.
MongoDB Authentication & Authorization + End-to-End Encryption: architecture patterns and best practices
Continue reading? Get the full guide.
Free. No spam. Unsubscribe anytime.
Once you spot the out-of-sync router or shard, refresh its metadata cache. Ask a cluster admin to run a routing table refresh on the affected nodes. This forces the node to pull the latest chunk map from the config servers. If a stuck chunk migration caused the conflict, wait for the balancer to finish.
Never fix metadata errors by editing config database tables with a readWrite role. The readWrite role allows insert, update, remove, and dropCollection actions on user data. Using write roles on internal routing tables often corrupts the whole cluster. Always use built-in cluster flush commands so the database checks safety rules first.
Preventing metadata mismatches during routine maintenance
You can avoid most code 105 errors by following safe change habits. When you drop a sharded collection, wait before making a new one with the same name. Give all routers time to learn that the old collection is gone.
Keep user permissions tight so apps and people cannot alter sharding state by mistake. MongoDB Atlas database users have different built-in roles than self-hosted users. Still, both models use the same core privilege actions. Give engineers read-only roles for daily debugging. Require peer review before anyone runs commands that change shard keys or collection layouts. Also, mask sensitive fields like emails, phone numbers, card numbers, and national IDs in query results.
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
What does IncompatibleShardingMetadata mean in MongoDB?
It means two nodes in a sharded cluster disagree on the sharding metadata version. The database blocks the operation so it does not write or read data on the wrong shard.
Can I fix mongodb error 105 without restarting the whole cluster?
Yes, you rarely need a full restart to clear this error. Flushing the routing table cache on the affected router or shard usually fixes the mismatch right away.
Does the built-in read role let me check collection stats during this error?
Yes, the read role includes actions like collStats, dbStats, listCollections, and listIndexes. You can inspect collection state safely without having permissions to modify or drop data.
Related guides
In this post