How to Fix MongoDB Error 121 (DocumentValidationFailure)
You get mongodb error 121 when a write breaks your collection schema validation rules. To fix it, update the document payload to match the required fields and data types. In the official database specs, code 121 maps to DocumentValidationFailure. The database engine blocks the insert or update before writing bad data to disk. This protects your collections from broken app updates or bad manual edits. Root causes of mongodb error 121 in your database Schema rules sit on a collection and check
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 121 when a write breaks your collection schema validation rules. To fix it, update the document payload to match the required fields and data types.
In the official database specs, code 121 maps to DocumentValidationFailure. The database engine blocks the insert or update before writing bad data to disk. This protects your collections from broken app updates or bad manual edits.
Root causes of mongodb error 121 in your database
Schema rules sit on a collection and check every new or changed document. When an app sends an insert or update, the engine tests the document first. If one field fails the check, the database rejects the write and returns code 121.
Missing required fields cause this failure most of the time. A collection rule might ask for an email string or an account status value. If the client sends a payload without that key, the write fails right away.
Wrong data types also trigger DocumentValidationFailure during daily writes. For example, the rule may expect an integer, but the app sends a text string. Null values also fail when a schema rule demands a strict type.
Manual fixes by engineers can cause this error too. An operator with a readWrite role can run insert, update, and remove actions on collections. Even with write rights, the engine still checks every change against the schema rules.
Nested objects and arrays often hide subtle type errors. A deep field might fail a numeric range check or a text pattern check. Modern database logs tell you the exact field that broke the collection rule.
How to diagnose and fix the failure in production
Start by reading the full error message in your app logs or database logs. The server output lists the exact rule and field that failed the check. Do not turn off schema validation just to force a write through.
Next, inspect the collection rules using a safe account. A standard read role lets you run listCollections and find actions on non-system collections. It does not allow insert, update, remove, or dropCollection actions, which keeps production data safe.
MongoDB Authentication & Authorization + End-to-End Encryption: architecture patterns and best practices
Continue reading? Get the full guide.
Free. No spam. Unsubscribe anytime.
Compare the rejected document payload against the collection schema rules side by side. Check every required field name for spelling mistakes or missing keys. Verify that numbers, booleans, dates, and sub-documents use the exact expected types.
If you inspect live production records, watch out for private user data. Data masking rewrites matched fields like emails, phone numbers, card numbers, and national IDs in results. This helps engineers check document shapes safely during an incident.
Once you find the mismatch, fix the payload in your app code. Add unit tests that check document types before the app sends writes to the database. If the schema rule itself is outdated, update the rule through your normal release process.
Remember that MongoDB grants access down to a collection level through role-based rules. Keep write roles tight so only approved services and changes can alter collection rules. Good role hygiene stops ad-hoc writes from breaking your data layout.
Preventing schema failures across app releases
Schema errors often spike when teams deploy new app versions. If the app code changes before the database rule updates, writes will fail. Sync your schema updates with your code releases to avoid sudden outages.
Test your new document shapes in a staging database before going live. Keep staging collection rules identical to your production collection rules. Catching a code 121 error in staging saves hours of stress later.
When you add a new required field, roll it out in two clear steps. First, update the app to write the new field and backfill old records. Second, enable the strict collection rule once all writes include the new key.
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 DocumentValidationFailure mean in MongoDB?
DocumentValidationFailure is the official name for mongodb error 121. It means an insert or update broke the validation rules set on the target collection.
Can a user with the readWrite role still get error 121?
Yes, the readWrite role allows insert and update actions, but schema rules still apply. The database checks the document structure even when the user has write permissions.
How can I check collection rules without risking data changes?
Use an account with the built-in read role to inspect the database safely. The read role allows find and listCollections actions without granting insert, update, or remove rights.
Related guides
In this post