How to Fix MongoDB Error 200 (ChunkRangeCleanupPending)

Published
Length
3 min read

Luis Felipe Dias

All posts

You see mongodb error 200 when a shard cannot move a data chunk yet. You fix this ChunkRangeCleanupPending error by waiting for old range deletions to finish. Sharded clusters split large data sets across multiple servers. When the balancer moves a chunk, the source shard must delete the old docs. If a new move starts before cleanup ends, the engine throws code 200. This safety check stops duplicate keys and data corruption across your cluster. What causes mongodb error 200 in sharded cluster

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 200 when a shard cannot move a data chunk yet. You fix this ChunkRangeCleanupPending error by waiting for old range deletions to finish.

Sharded clusters split large data sets across multiple servers. When the balancer moves a chunk, the source shard must delete the old docs. If a new move starts before cleanup ends, the engine throws code 200. This safety check stops duplicate keys and data corruption across your cluster.

What causes mongodb error 200 in sharded clusters

The internal name for mongodb error 200 is ChunkRangeCleanupPending. It happens during chunk migrations between shards in a cluster. When a chunk moves from Shard A to Shard B, Shard A keeps copies briefly. Open cursors or long queries on Shard A might still read those docs.

Once those queries finish, the shard deletes the orphaned range in the background. If the balancer tries to move that same range back, a conflict happens. The shard refuses the incoming chunk because old docs still sit on disk. Heavy write loads or slow disks also delay this background deletion task. Secondary replication lag can also pause range deletions when write concerns wait for acks.

How to diagnose and fix the failure in production

Start by checking your cluster logs and shard stats with a safe role. MongoDB grants access through roles that apply to specific databases and collections. You do not need full admin rights just to inspect cluster state. The built-in read role grants actions like find, listCollections, dbStats, and collStats.

Use an account with read privileges to check for long-running queries first. Open cursors on the target collection block the range deleter from removing old docs. Once those read operations finish or time out, the cleanup queue moves forward. Check disk utilization on the affected shard to see if storage bottlenecks exist.

MongoDB Authentication & Authorization + End-to-End Encryption: architecture patterns and best practices

Continue reading? Get the full guide.

Free. No spam. Unsubscribe anytime.

If you must cancel a stuck query or change balancer state, scope privileges tightly. Never grant broad write roles to every engineer who investigates an alert. The readWrite role allows insert, update, remove, and dropCollection actions on data. Keep normal debug sessions on read-only roles and require approval for state changes. If you inspect user docs during debug, make sure masking rewrites emails and card numbers in results.

Preventing future chunk cleanup delays

You can lower the chance of seeing code 200 by tuning query timeouts. Set reasonable time limits on client reads so cursors do not keeps the session active forever. Schedule heavy batch jobs outside of peak balancer windows when possible. Monitor replication lag across replica sets so range deletions do not stall waiting for secondaries.

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

Does ChunkRangeCleanupPending cause data loss?

No, this error prevents data corruption rather than causing data loss. The shard rejects a new chunk move until old orphaned docs are deleted.

Can I delete orphaned documents manually to clear error 200?

You should let the built-in background range deleter finish its work instead. Manual deletion risks removing active data if you misread the chunk boundaries.

What database role do I need to check collection stats during this error?

The standard read role gives you access to dbStats, collStats, and find actions. It lets you inspect collection metrics without allowing insert, update, or remove actions.

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.

The query runs. The emails stay hidden.