How to Fix MongoDB Error 153 (ChunkTooBig)
You see mongodb error 153, also known as ChunkTooBig, when a data chunk exceeds the size limit during a migration. You fix it by splitting the oversized chunk or refining the shard key so the cluster can divide the data. Sharded clusters group documents into contiguous key ranges called chunks. A background balancer moves these chunks across shards to keep data even. When a chunk grows too large to move, the cluster raises code 153 and stops the migration. What causes mongodb error 153 in a s
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 153, also known as ChunkTooBig, when a data chunk exceeds the size limit during a migration. You fix it by splitting the oversized chunk or refining the shard key so the cluster can divide the data.
Sharded clusters group documents into contiguous key ranges called chunks. A background balancer moves these chunks across shards to keep data even. When a chunk grows too large to move, the cluster raises code 153 and stops the migration.
What causes mongodb error 153 in a sharded cluster
The database engine returns the ChunkTooBig error when a chunk exceeds the allowed migration threshold. In normal operations, the cluster splits chunks before they reach the limit. Several cluster and data patterns can block this split.
The most common cause is a shard key with low cardinality. When many documents share the exact same shard key value, they form a jumbo chunk. The engine cannot split a chunk that holds only one shard key value.
Sudden bulk writes can also trigger this failure condition. If an app inserts data faster than the split process runs, a chunk can grow past the limit. Once the chunk is too big, the balancer refuses to move it to another shard.
Finally, a single huge document or a dense range of large documents can push a chunk over the size limit. When the balancer tries to move that range, the migration fails with code 153.
How to diagnose and fix oversized chunks in production
Start your check with a low-privilege database role. In MongoDB, roles grant actions on resources down to a collection level of granularity. The built-in read role lets you inspect collection stats and find documents without the risk of data changes.
Use read actions to inspect the shard distribution and find the exact key range that failed. Check whether the chunk has many distinct shard keys or just one repeated value. This step tells you which fix to apply.
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 chunk contains many distinct shard key values, run a manual split command on that key range. Splitting breaks the oversized range into smaller chunks. Once the chunks are smaller, the balancer can move them across shards again.
If all documents in the chunk share one shard key value, a simple split will not work. You must refine the shard key by adding a suffix field with higher cardinality. If you cannot refine the key, you must reshard the collection with a better key distribution.
Controlling privileges during cluster repair
Fixing sharding issues requires elevated cluster actions, while routine checks only need read access. Avoid giving every engineer permanent admin rights on production shards. Split diagnosis from repair so you keep production data safe.
During diagnosis, engineers may inspect documents to see why a shard key skewed. Those documents often hold sensitive fields like emails, phone numbers, card numbers, or national IDs. Masking rewrites matched fields in query results during these checks.
When a team member needs to run a split or refine a shard key, grant write or admin privileges only for that task. Log every command run against the cluster so you have a clear audit trail of the fix.
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 the ChunkTooBig error code 153 mean in MongoDB?
Error 153 means a shard chunk is larger than the maximum size allowed for chunk migration. The balancer cannot move the chunk to another shard until you reduce its size.
Why can the cluster not split a jumbo chunk on its own?
A chunk splits along shard key boundaries. If every document in the chunk has the exact same shard key value, there is no boundary point where the engine can divide the data.
Can I inspect collection stats without granting write permissions?
Yes. The built-in read role grants actions like collection stats, database stats, and find on non-system collections while blocking insert, update, remove, and drop actions.
Related guides
In this post