How to Fix MongoDB Error 383 (CollectionIsEmptyLocally)
You get mongodb error 383 when a command expects local data, and the collection is empty. This error has the official name CollectionIsEmptyLocally. You can fix it by checking shard metadata, routing queries right, or waiting for data sync. Database teams often see this code during cluster changes or direct node checks. When an app or operator runs a task against a specific node, that node checks its local storage. If the local slice of the collection holds zero records, the database stops the
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 383 when a command expects local data, and the collection is empty. This error has the official name CollectionIsEmptyLocally. You can fix it by checking shard metadata, routing queries right, or waiting for data sync.
Database teams often see this code during cluster changes or direct node checks. When an app or operator runs a task against a specific node, that node checks its local storage. If the local slice of the collection holds zero records, the database stops the task and returns code 383. Knowing why the local node lacks data helps your team fix the issue without risking production safety.
What causes mongodb error 383 in your cluster
The database engine uses code 383 to flag aCollectionIsEmptyLocally state. In a distributed setup, data lives across many nodes or shards. A collection might exist in the global cluster catalog while holding no documents on one specific shard. When an internal task or admin command demands local documents to finish its work, the engine raises this error.
Several common events create an empty local collection. First, a new collection might exist on paper before any app writes documents to that shard. Second, chunk migrations or balancing work might move all documents off a specific shard. Third, a user or script might connect straight to a single shard member instead of the main cluster router. Direct node checks bypass cluster routing and look only at local storage.
Network paths and client settings also play a part. If a client tool points to a secondary node or an isolated shard during maintenance, local state might lag behind the primary router view. The node sees the collection name in its local catalog, checks the storage engine, finds zero records, and triggers code 383.
How to diagnose and fix the failure safely
Fixing this error starts with safe read-only checks. Your team should not grant broad admin rights just to inspect a collection state. MongoDB grants access through role-based rules that apply to a specific database and work down to the collection level. You can give an engineer the built-in read role on the target database. This role allows safe actions like find, listCollections, listIndexes, dbStats, and collStats on non-system collections.
Using collStats and listCollections lets the responder see if the collection holds data across the cluster or sits empty on one node. The read role does not allow insert, update, remove, or dropCollection actions. This keeps production data safe while the engineer checks why the local collection has no records.
MongoDB Authentication & Authorization + End-to-End Encryption: architecture patterns and best practices
Continue reading? Get the full guide.
Free. No spam. Unsubscribe anytime.
Once you confirm the collection is empty locally, pick the right fix for your workload. Make sure apps and scripts connect through the cluster router instead of hitting a single shard directly. If a background job or maintenance task needs data before running, add a quick count check first. If a migration left a shard empty, let the cluster balancer finish its run or refresh the router metadata.
Preventing local collection errors in daily operations
Good access habits stop this error from surprising your on-call team. Many local collection errors happen when engineers log in to individual nodes to run manual fixes. When teams connect through a central point with scoped roles, queries hit the right cluster layer every time.
If a fix requires writing seed data or dropping an unused collection, step up to the readWrite role only for that task. The readWrite role adds insert, update, remove, createCollection, and dropCollection actions on top of read access. Keep those write actions scoped to the single collection that needs the fix, and switch back to read-only access when done.
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 CollectionIsEmptyLocally mean in MongoDB?
CollectionIsEmptyLocally is the official name for error code 383. It means the target collection exists on the local node, but it contains zero documents right now.
Which role do I need to check collection stats safely?
You only need the built-in read role on the target database. It allows listCollections, dbStats, and collStats without letting users change or delete any data.
Does error 383 mean my cluster lost production data?
No, this error usually means the specific node you queried holds no local records. Your data often lives on other shards, or the collection is brand new.
Related guides
In this post