How to Fix MongoDB Error 414 (AddOrRemoveShardInProgress)
You get mongodb error 414 when your cluster is already adding or removing a shard. To fix it, wait for the active shard change to finish before you run another one. MongoDB names this failure AddOrRemoveShardInProgress in its official error list. The cluster blocks new topology changes until the current shard task completes. This safety rule protects your data layout during big cluster updates. Why mongodb error 414 happens in sharded clusters A sharded cluster splits data across many server
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 414 when your cluster is already adding or removing a shard. To fix it, wait for the active shard change to finish before you run another one.
MongoDB names this failure AddOrRemoveShardInProgress in its official error list. The cluster blocks new topology changes until the current shard task completes. This safety rule protects your data layout during big cluster updates.
Why mongodb error 414 happens in sharded clusters
A sharded cluster splits data across many servers. When you add or remove a shard, the balancer moves data chunks around. This process takes time, especially when your database holds a lot of data.
If an admin or script sends a second shard change request during this time, the cluster rejects it. The engine returns code 414 right away. It will not queue the second shard command for you.
Automated deploy scripts trigger this error most often. A deploy pipeline might run two cluster tasks back to back. If the first task does not wait for all data chunks to move, the next step fails. Two admins working on the same cluster at the same time can also hit this conflict.
Long data moves make this problem worse. Removing a shard requires the cluster to drain every chunk from that server first. Until the last chunk moves to a new home, the removal stays in progress. Any new add or remove request during that drain window will fail with code 414.
How to check and fix the error safely in production
Do not restart servers or force stop the balancer when you see this error. Stopping a shard change midway leaves data unbalanced and wastes hours of work. Instead, check the current state of your cluster first.
Start by viewing your cluster status logs and shard list. You do not need full admin rights just to inspect cluster health. MongoDB grants access through roles that define allowed actions on specific resources. A role applies to a database and can grant access down to the collection level.
MongoDB Authentication & Authorization + End-to-End Encryption: architecture patterns and best practices
Continue reading? Get the full guide.
Free. No spam. Unsubscribe anytime.
For normal data checks, the built-in read role grants safe inspection actions. It lets users run find, listCollections, listIndexes, dbStats, and collStats on non-system collections. It blocks insert, update, remove, and dropCollection actions so nobody changes data by mistake. Giving engineers read-only roles for initial checks keeps your production data safe.
Look at the active shard state to see if a shard is still draining. Check the balancer status to see how many data chunks remain on that shard. If a shard removal is running, let the balancer finish moving those chunks.
Sometimes an unsharded collection still lives on the primary shard you want to remove. When that happens, the removal pauses until an admin moves that collection to another shard. Once the shard holds zero chunks and zero collections, the removal finishes.
How to prevent shard conflicts in your team
Good team habits stop code 414 before it starts. First, update your automation scripts so they poll the cluster state. A script should check that no shard task is active before it sends a new one. After sending a remove request, the script must wait until the shard list updates.
Second, limit who can run shard commands in production. Most developers only need the read role or the readWrite role for daily app work. The readWrite role adds data change actions like insert, update, remove, createCollection, and createIndex. Neither of these app roles allows a user to add or remove shards.
Keep cluster admin roles restricted to a small group of platform engineers. When your team needs to run a shard change, use a single approval queue. That way, two engineers never run conflicting shard tasks at the same time. Also, if engineers inspect production data during a fix, make sure masking rewrites emails, phone numbers, and card numbers 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 AddOrRemoveShardInProgress mean in MongoDB?
It means the cluster is busy adding or removing a shard right now. MongoDB returns error code 414 to block new shard changes until the active task finishes.
Does mongodb error 414 break normal app reads and writes?
No, normal app queries keep running while the cluster moves data chunks in the background. Error 414 only blocks new admin commands that try to add or remove another shard.
Why does removing a shard take so long to finish?
The cluster must move every data chunk off that shard before removing it. If you have large collections or slow network links, draining those chunks takes many hours.
Related guides
In this post