How to Fix MongoDB Error 163 (ZoneStillInUse)

Published
Length
3 min read

Luis Felipe Dias

All posts

You get mongodb error 163 when you remove a shard from an active zone. To fix this ZoneStillInUse error, remove all shard key ranges from that zone first. Sharded clusters use zones to control where data lives across your servers. A shard cannot leave a zone while key ranges still point to that zone. The database blocks the removal to stop data from losing its routing rules. You must clear those key ranges before you drop the shard association. Root causes of mongodb error 163 in sharded clus

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 163 when you remove a shard from an active zone. To fix this ZoneStillInUse error, remove all shard key ranges from that zone first.

Sharded clusters use zones to control where data lives across your servers. A shard cannot leave a zone while key ranges still point to that zone. The database blocks the removal to stop data from losing its routing rules. You must clear those key ranges before you drop the shard association.

Root causes of mongodb error 163 in sharded clusters

In the database engine, code 163 maps to the official ZoneStillInUse error name. This failure happens during cluster maintenance when teams change how shards map to zones. Admins often try to remove a zone from a shard right away. If a collection still assigns shard key ranges to that zone, the command fails.

The cluster tracks zone rules inside its internal metadata catalog. When you ask the cluster to drop a shard from a zone, it checks this catalog. If the zone still holds active key ranges, the engine throws mongodb error 163. This check happens even if the collection holds zero documents in that range. An empty key range still counts as an active rule in the cluster metadata.

This issue also appears when automated scripts run cluster changes in the wrong order. A script might try to clean up shard associations before it clears collection ranges. Network delays between config servers rarely cause this specific error. It is almost always a state mismatch in your zone routing rules.

How to diagnose and fix ZoneStillInUse safely in production

Start by checking your cluster metadata to see which collections use the target zone. You do not need full admin rights just to inspect cluster routing states. MongoDB grants access through role-based rules that apply to a database or collection. A standard read role allows actions like find, listCollections, and listIndexes on non-system data. Give your engineers read-only roles while they check which ranges block the change.

Once you find the active key ranges, plan your update with care. Removing a zone range changes how the balancer moves data chunks across shards. First, delete or update the zone key ranges on the affected collections. Wait for the cluster metadata to record that no ranges use the zone.

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

Continue reading? Get the full guide.

Free. No spam. Unsubscribe anytime.

After you clear the key ranges, run the command to remove the shard from the zone. The ZoneStillInUse check will pass now because the zone has no active range rules. Let the cluster balancer move any remaining chunks according to your new layout. Watch your cluster load to make sure chunk moves do not hurt app traffic.

How to prevent zone errors during cluster updates

Many zone errors happen when too many people run manual cluster commands at once. You should limit who can change shard rules in your live database. In MongoDB, roles grant specific sets of actions on defined resources. Keep write roles and cluster admin rights away from daily user accounts.

When an engineer needs to fix a zone rule, grant only the needed actions. Keep an audit log of every command that changes shard zones or key ranges. If a script manages your zones, make it check for active ranges before dropping shards. You can also apply data masking to rewrite emails or phone numbers in query results. This protects user data while engineers inspect collections during a cluster fix.

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 the ZoneStillInUse message mean in MongoDB?

ZoneStillInUse means a zone still has shard key ranges tied to a collection. The database stops you from removing a shard from that zone until you clear those ranges.

Does mongodb error 163 cause data loss or downtime?

No, this error is a safety check that stops bad routing changes. Your cluster keeps running normal read and write traffic when this command fails.

Can I fix error 163 with a read-only database role?

You can inspect collections with a read role, which allows find and listCollections actions. Still, you need cluster admin permissions to drop zone ranges and update shards.

The query runs. The emails stay hidden.