How to Fix MongoDB Error 21 (EmptyArrayOperation)
You get mongodb error 21 when a query or write sends an empty array to an array operator. You fix it by checking that your app never runs an array operation with zero items. MongoDB names this failure EmptyArrayOperation in its official error catalog. The database rejects the command before it changes or reads any records. Teams see this issue most often when dynamic code builds queries from user input. Why mongodb error 21 happens in your database Database engines expect valid data structur
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 21 when a query or write sends an empty array to an array operator. You fix it by checking that your app never runs an array operation with zero items.
MongoDB names this failure EmptyArrayOperation in its official error catalog. The database rejects the command before it changes or reads any records. Teams see this issue most often when dynamic code builds queries from user input.
Why mongodb error 21 happens in your database
Database engines expect valid data structures when they parse a command. Some operators need a list of values or documents to do their work. When your app passes an empty list, the engine cannot decide what to do. It stops the run right away and returns code 21 to the client.
This problem often starts in the app layer during a data lookup. For example, a first query might look up a list of user IDs. If that lookup finds nothing, it returns an empty array to the app. The app then passes that empty array into a second query or bulk write.
Bad input from a web form or API call can also trigger this bug. A user might submit a form with no items checked in a filter list. If the backend code does not check the array length, the database throws EmptyArrayOperation. Batch jobs face the same risk when they slice large data sets into chunks. An off-by-one math mistake at the end of a loop can create an empty batch.
How to find and fix the empty array failure
To find the broken command, you must check your app logs and database logs. You should not grant full admin rights to developers just to read production data. MongoDB grants access through roles that allow specific actions on defined resources. A role applies to its own database and works down to the collection level.
When an engineer needs to inspect data, assign the built-in read role on that database. The read role allows actions like find, listCollections, listIndexes, dbStats, collStats, and changeStream. It applies to all non-system collections and the system.js collection in that database. It does not allow insert, update, remove, or dropCollection actions, which keeps production data safe. During these checks, data masking rewrites matched fields like emails or phone numbers in results.
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 spot the failing query, fix the logic in your app code. Add a simple check to test the array length before you send the command. If the array has zero items for a write job, skip the database call. If an array filter is empty during a read, return an empty result right away. This simple check stops the error and saves a trip to the database server.
How to prevent empty array bugs in production
Good testing catches empty array bugs before your code reaches the production cluster. Write unit tests that pass empty lists into every data helper in your app. Make sure your code handles zero-length arrays without calling the database driver at all. You can also add schema checks at your API border to reject empty lists early.
When you need to fix bad records in production, keep write permissions tight. The readWrite role includes everything in the read role plus actions to modify data. Its actions cover insert, update, remove, createCollection, createIndex, dropIndex, and dropCollection on that database. Only grant this role for the exact time needed to run your tested 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 EmptyArrayOperation mean in MongoDB?
EmptyArrayOperation is the official name for error code 21 in the database engine. It means a command passed an empty array to an operation that requires one or more items.
Does error 21 corrupt any data in my collection?
No, this error does not corrupt or change any stored documents in your collection. The database stops the command during the check phase before any disk write happens.
Which role should engineers use to debug this error in production?
Assign the built-in read role on the target database so engineers can run find queries. This role blocks insert, update, and remove actions so nobody changes live records by mistake.
Related guides
In this post