How to Fix MongoDB Error 87 (CannotSplit)

Published
Length
3 min read

Luis Felipe Dias

All posts

You see mongodb error 87 when the database engine fails to divide a data chunk. You fix this CannotSplit failure by checking shard keys and balancing chunk sizes. Sharded clusters split large chunks to spread data across multiple servers. When a chunk cannot divide, data builds up on a single shard. This imbalance slows down read and write requests across your app. Understanding why splits fail helps your team keep the cluster healthy and fast. What causes mongodb error 87 in 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 87 when the database engine fails to divide a data chunk. You fix this CannotSplit failure by checking shard keys and balancing chunk sizes.

Sharded clusters split large chunks to spread data across multiple servers. When a chunk cannot divide, data builds up on a single shard. This imbalance slows down read and write requests across your app. Understanding why splits fail helps your team keep the cluster healthy and fast.

What causes mongodb error 87 in sharded clusters

In the official error list, code 87 maps to the CannotSplit error name. This error happens inside a sharded cluster during chunk management tasks. The database engine splits chunks when they grow past the target size. Manual split requests from an admin can also trigger this exact error code.

A common root cause is a poor shard key with low variety. If too many documents share the exact same shard key value, they stay together. The engine cannot divide a group of documents that have identical shard keys. These indivisible groups are often called jumbo chunks by database teams.

Empty chunks or wrong split points also cause the CannotSplit failure. If an admin asks the cluster to split a chunk at a missing value, it fails. Heavy write traffic on one shard can also block the split process. Network drops between config servers and shards can interrupt metadata updates during a split.

How to diagnose mongodb error 87 safely

Start your check by looking at chunk sizes and shard key values. Your team does not need full admin rights just to inspect collection stats. MongoDB uses role-based rules to grant actions on specific databases and collections.

Assigning the built-in read role lets an engineer check database and collection stats safely. The read role allows actions like finding documents, listing indexes, and reading collection stats. It blocks actions that change data, such as inserts, updates, removes, or dropping collections. Using read-only roles during the check stage protects production data from mistakes.

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

Continue reading? Get the full guide.

Free. No spam. Unsubscribe anytime.

Look at the distribution of shard key values inside the problem chunk. Check if a single key value makes up the entire chunk size. Review the cluster logs to see if config servers had network timeouts. Also check if a manual split command used a boundary outside the chunk range.

How to fix and prevent chunk split failures

Once you find the root cause, plan a safe fix for your cluster. If a manual split used a bad split point, pick a valid middle key. Make sure the chosen split key exists inside the target chunk boundaries.

If an indivisible chunk causes the error, you must rethink your shard key design. Pick a compound shard key that gives the collection a wider range of values. High variety in shard keys lets the engine divide chunks at many points. You may need to refine the shard key or move data to a new collection.

When applying fixes that change data or indexes, grant only the needed role. The readWrite role adds the ability to insert, update, remove, and create indexes. Only give out write roles for the exact time needed to fix the shard. Mask sensitive fields like emails, phone numbers, card numbers, and national IDs during checks. Data masking rewrites matched fields in query results to keep user info safe.

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

What does error code 87 mean in MongoDB?

Error code 87 is the CannotSplit error in a sharded database cluster. It means the database could not divide a sharded data chunk into smaller parts.

Can a bad shard key trigger the CannotSplit error?

Yes, a shard key with very few unique values often causes this error. The database cannot split a chunk if all documents share the same key value.

What role do I need to check collection stats for chunk issues?

The built-in read role lets you run collection stats and database stats commands. It lets you inspect the database without allowing any data changes or drops.

The query runs. The emails stay hidden.