How to Fix MongoDB Error 520 (DDLCoordinatorMustRetryDueToFCVTransition)
You see mongodb error 520 when a schema change runs during a feature version update. To fix it, wait for the version change to finish and retry your command. MongoDB names this error DDLCoordinatorMustRetryDueToFCVTransition in its internal error list. The database marks code 520 as an internal only error. It stops data definition tasks when the cluster changes its feature level. This rule protects cluster metadata from splitting across different node versions. What causes mongodb error 520 i
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 520 when a schema change runs during a feature version update. To fix it, wait for the version change to finish and retry your command.
MongoDB names this error DDLCoordinatorMustRetryDueToFCVTransition in its internal error list. The database marks code 520 as an internal only error. It stops data definition tasks when the cluster changes its feature level. This rule protects cluster metadata from splitting across different node versions.
What causes mongodb error 520 in your cluster
A MongoDB cluster uses a feature setting to control which engine features stay active. Cluster admins change this setting during major database upgrades or downgrades. While that change runs, nodes update their internal system tables in the background.
If an app or admin starts a collection change at that exact time, a clash happens. The data definition coordinator sees the version shift and stops its current work. It throws code 520 so the internal coordinator knows it must try again later. In most cases, the database handles this retry on its own. You only see the error in logs or when the version shift gets stuck.
Network drops between shards can also freeze a version update mid-way. When a primary node steps down during an upgrade, the version task pauses. Any collection creation, index build, or drop action will then hit code 520. The coordinator keeps hitting this wall until the cluster finishes its version transition.
How to diagnose and fix the failure in production
Start by checking your cluster logs to see if a version change is active. You only need read access to check cluster state and collection stats. MongoDB grants access through role-based rules down to the collection level. A basic read role lets you run stats and list collections safely. Do not grant full admin rights to engineers just to inspect this error.
Check if all replica set members and shards are online and healthy. If a node is down, the version change cannot finish its work across the cluster. Bring the offline node back or fix the network path between your database nodes. Once all nodes talk to each other, the background version task can move forward.
MongoDB Authentication & Authorization + End-to-End Encryption: architecture patterns and best practices
Continue reading? Get the full guide.
Free. No spam. Unsubscribe anytime.
If the version update stopped partway, an admin must run the version command again. Wait until the cluster reports that the target version is fully set everywhere. Keep schema changes paused while this admin task runs on the cluster. After the version state settles, the DDL coordinator will stop throwing code 520.
Review your deployment scripts so schema changes do not run during engine upgrades. Many teams run collection updates by default when an app starts up. If an app boots during a database upgrade, it can trigger this conflict. Separate your database version upgrades from your app schema changes to avoid this race.
How to prevent role sprawl during database fixes
Production errors often tempt teams to hand out broad write roles for quick fixes. In MongoDB, the readWrite role lets users create or drop collections and indexes. Giving that role to every developer increases the risk of accidental schema changes. If someone drops a collection during an upgrade, they will trigger more coordinator errors.
Keep everyday users on the read role so they can only view data. The read role includes find, list collections, list indexes, and collection stats actions. It blocks insert, update, remove, and drop collection actions by default. When an engineer needs to fix a stuck upgrade, use strict approval checks first. Mask sensitive fields like emails, phone numbers, and card numbers in query results. Data masking rewrites matched fields in results while engineers inspect cluster state.
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
Is mongodb error 520 a sign of data corruption?
No, code 520 is a safety check that prevents metadata damage during upgrades. The database stops the schema task cleanly so your stored data stays safe.
Do I need to restart my database nodes to clear code 520?
No, restarting nodes usually slows down the active feature version transition. Let the cluster finish its version update while all nodes stay online.
Why does an internal only error show up in my logs?
MongoDB logs internal coordinator retries so admins can track slow schema tasks. If it repeats often, your feature version transition is likely stuck on one node.
Related guides
In this post