How to Fix MongoDB Error 405 (CannotCreateChunkDistribution)

Published
Length
3 min read

Luis Felipe Dias

All posts

You see mongodb error 405 when a sharded cluster fails to build a chunk map. You fix this CannotCreateChunkDistribution error by checking your shard key, zone rules, and shard health. Sharded clusters split large data sets into smaller blocks called chunks. The database engine then spreads these chunks across your active shards. When the cluster cannot plan where new chunks go, the command stops right away. Your team must check the cluster state before running the sharding step again. What tr

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 405 when a sharded cluster fails to build a chunk map. You fix this CannotCreateChunkDistribution error by checking your shard key, zone rules, and shard health.

Sharded clusters split large data sets into smaller blocks called chunks. The database engine then spreads these chunks across your active shards. When the cluster cannot plan where new chunks go, the command stops right away. Your team must check the cluster state before running the sharding step again.

What triggers mongodb error 405 in sharded clusters

In the official server error list, code 405 maps to the name CannotCreateChunkDistribution. This failure happens during collection sharding or initial chunk setup on a cluster. The routing service asks the config servers to calculate an initial chunk layout. If the math or the shard layout fails, the engine returns code 405.

Several cluster states can block this chunk layout step. First, the target shards might not be online or ready to take data. Second, your zone sharding ranges might have gaps or bad bounds. If no shard matches a required zone range, the cluster has nowhere to put chunks.

Third, the chosen shard key or chunk count might conflict with current cluster limits. When you ask for too many initial chunks, the config server can reject the plan. Network drops between the router and the config servers can also break this step. In every case, the database stops the command to protect your existing data.

How to diagnose the chunk layout failure

Start your check by reading the cluster metadata with a safe read role. MongoDB grants access through roles that define allowed actions on specific resources. A role applies to its home database and can control access down to a collection. Your engineers do not need full admin rights just to inspect collection states.

The built-in read role grants read access to all non-system collections in a database. It lets an engineer run actions like find, listCollections, listIndexes, dbStats, and collStats. Using these read actions, your team can check existing indexes on the target collection. A sharded collection needs a valid index that starts with the exact shard key.

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

Continue reading? Get the full guide.

Free. No spam. Unsubscribe anytime.

Next, check the list of active shards and any zone tag rules. Look for typos in zone names or shard tags that leave a range empty. Make sure the minimum and maximum bounds for each zone match your shard key type. Also verify that every shard in the cluster can talk to the config servers.

How to fix the error safely in production

Once you find the root cause, plan a clean fix with least privilege. If the collection lacks the right index, an authorized user must create it first. The readWrite role includes everything in the read role plus data change actions. It lets a user run createCollection, createIndex, dropIndex, insert, update, and remove.

If bad zone ranges caused the failure, fix the zone bounds before sharding the collection. Ensure every zone links to at least one online shard in the cluster. If a shard was down during the first try, wait until it rejoins the cluster. Do not turn off cluster safety checks just to force a command through.

When engineers inspect live collections during a fix, keep private user data safe. Masking rules can rewrite matched fields like emails, phone numbers, card numbers, or national IDs. This keeps sensitive records protected while your team runs diagnostic queries on the cluster. After you fix the shard tags and indexes, run the collection sharding step again.

Check MongoDB commands and documents on the wire

MongoDB roles and SCRAM login decide who opens a session. They do not check single commands or redact sensitive fields inside returned documents. With hoop.dev, you run an open-source proxy, a sidecar for your MongoDB, inline in the MongoDB wire protocol. On every command an AI agent or engineer runs against production, hoop.dev decides to pass, mask, block, or hold it for human review.

Before a command runs, hoop.dev guardrails check its effect and refuse banned drops or writes with MongoDB error code 13, or hold risky commands for approval. On the way back, hoop.dev data masking rewrites sensitive fields in returned documents in memory, and every verdict is logged. See the open-source code on GitHub.

Frequently asked questions

What does error code 405 mean in MongoDB?

Error code 405 is the official CannotCreateChunkDistribution error in a sharded cluster. It means the database could not plan or build the chunk layout across shards.

Does mongodb error 405 delete or corrupt existing data?

No, this error stops the sharding operation before the cluster moves any collection data. Your existing records stay intact while you fix the shard key or zone setup.

Which role lets an engineer check indexes before sharding a collection?

The built-in read role lets a user run listIndexes and collStats on a database. A user needs the readWrite role or higher to run createIndex on that collection.

The query runs. The emails stay hidden.