MongoDB Error 121

Error code

121

Code name

DocumentValidationFailure

Product

MongoDB

Versions

MongoDB 7.0 and 8.0 (format checked against the 8.0 source and documentation)

Category

Writes & Validation

Last reviewed

24 October 2026

What it means

Error 121 (DocumentValidationFailure) means an insert or update would leave a document that breaks the collection's validator, such as a $jsonSchema rule, so MongoDB rejected the write.

A collection can carry a validator: a $jsonSchema document or query operators that every inserted or updated document must satisfy. With the default validationAction: "error", a write that produces a document the validator does not match is rejected with code 121 and the fixed message Document failed validation (the string is a constant in MongoDB 8.0's collection code). The message never says which rule failed; the answer is in the errInfo document that comes with it, which mongosh prints as Additional information.

errInfo.failingDocumentId is the document's _id and errInfo.details is a tree of the rules that were not satisfied. Read it from the leaves: missingProperties lists required fields that are absent, propertiesNotSatisfied names each field that failed with a reason such as type did not match or regular expression did not match, and consideredValue and consideredType show what was actually sent. With additionalProperties: false the unexpected fields are listed under additionalProperties.

The validation level decides which writes are checked. The default strict checks every insert and update; moderate does not check updates to documents that were already invalid. MongoDB documents that adding or tightening rules does not check existing documents, but later updates to an invalid document fail until the document is made valid. A validator that uses only query operators (not $jsonSchema) reports failures with reasons such as field was missing.

Common causes

• A field listed in required is missing from the document (shown under missingProperties).
• A field has the wrong BSON type: a string where a number is expected, a date sent as a string, or a whole number stored as int where the rule says bsonType: "double".
• A value breaks a constraint such as pattern, enum, minimum, maximum or maxLength.
• The schema sets additionalProperties: false and the document contains a field the schema does not list.
• An update touches a document that was stored before the rules were added or tightened, and the result still breaks the current rules.
• The validator was changed (collMod or a migration) and the application was not updated to match.

Diagnose it

Read-only These mongosh commands only read data, indexes, statistics and server state (find, aggregate without $out or $merge, getIndexes, stats, currentOp, rs.status). They do not change data, users or settings, so they are safe to run first.

db.getCollectionInfos({ name: "contacts" })[0].options

const v = db.getCollectionInfos({ name: "contacts" })[0].options.validator
const candidate = { name: "Amanda", email: "amanda@xyz.com" }

db.aggregate([ { $documents: [ candidate ] }, { $match: v } ])

const v = db.getCollectionInfos({ name: "contacts" })[0].options.validator

db.contacts.find({ $nor: [ v ] }).limit(20)
db.contacts.countDocuments({ $nor: [ v ] })

db.contacts.aggregate([
  { $group: { _id: { $type: "$phone" }, docs: { $sum: 1 } } }
])

How to fix it

Each fix is labelled with what it changes. Try read-only checks and the least invasive fix first, and test changes outside production.

db.contacts.insertOne({
  name: "Amanda",
  phone: "+44 20 7946 0000",
  email: "amanda@mongodb.com"
})

db.runCommand({
  collMod: "products",
  validator: { $jsonSchema: {
    bsonType: "object",
    required: [ "name", "price" ],
    properties: {
      name:  { bsonType: "string" },
      price: { bsonType: "number", minimum: 0 }
    }
  } }
})

db.contacts.updateMany(
  { phone: { $exists: false } },
  { $set: { phone: "unknown" } }
)

db.runCommand({
  insert: "contacts",
  documents: [ { name: "Old record", email: "old@example.com" } ],
  bypassDocumentValidation: true
})

Examples

A missing required field and a value that breaks a pattern

Not reproduced here: no MongoDB server is installed for this site. The example and the result are the ones in MongoDB's documentation page "Choose How to Handle Invalid Documents"; the ObjectId is generated by the server and differs on every insert.

db.createCollection("contacts", {
  validator: { $jsonSchema: {
    bsonType: "object",
    required: [ "phone" ],
    properties: {
      phone: { bsonType: "string", description: "must be a string and is required" },
      email: { bsonType: "string", pattern: "@mongodb\\.com$",
               description: "must be a string and end with '@mongodb.com'" }
    }
  } },
  validationAction: "error"
})

db.contacts.insertOne({ name: "Amanda", email: "amanda@xyz.com" })

MongoServerError: Document failed validation
Additional information: {
  failingDocumentId: ObjectId("6377cca4aac957f2b77ea955"),
  details: {
    operatorName: '$jsonSchema',
    schemaRulesNotSatisfied: [
      {
        operatorName: 'properties',
        propertiesNotSatisfied: [
          {
            propertyName: 'email',
            description: "must be a string and end with '@mongodb.com'",
            details: [
              {
                operatorName: 'pattern',
                specifiedAs: { pattern: '@mongodb\\.com$' },
                reason: 'regular expression did not match',
                consideredValue: 'amanda@xyz.com'
              }
            ]
          }
        ]
      },
      {
        operatorName: 'required',
        specifiedAs: { required: [ 'phone' ] },
        missingProperties: [ 'phone' ]
      }
    ]
  }
}

A whole number where the rule says double

Not reproduced here: no MongoDB server is installed for this site. The detail fields (reason "type did not match", consideredValue, consideredType) are the ones built by MongoDB 8.0's validation error code (doc_validation_error.cpp, generateTypeError); MongoDB's "Query for and Modify Valid or Invalid Documents" page shows whole numbers entered in mongosh failing a double rule. The layout follows the documented example above and the ObjectId is left out.

db.createCollection("products", {
  validator: { $jsonSchema: {
    bsonType: "object",
    required: [ "name", "price" ],
    properties: {
      name:  { bsonType: "string" },
      price: { bsonType: "double" }
    }
  } }
})

db.products.insertOne({ name: "Pen", price: 2 })     // 2 is stored as int

MongoServerError: Document failed validation
Additional information: {
  failingDocumentId: ObjectId("..."),
  details: {
    operatorName: '$jsonSchema',
    schemaRulesNotSatisfied: [
      {
        operatorName: 'properties',
        propertiesNotSatisfied: [
          {
            propertyName: 'price',
            details: [
              {
                operatorName: 'bsonType',
                specifiedAs: { bsonType: 'double' },
                reason: 'type did not match',
                consideredValue: 2,
                consideredType: 'int'
              }
            ]
          }
        ]
      }
    ]
  }
}

How to prevent it

Keep the validator in version control next to the application code, change it with collMod in the same release as the code that depends on it, and run the $nor query before tightening a rule so you know how many stored documents will start failing on update.

Use the "number" alias unless a field really must be one numeric type, send dates as Date values, and log errInfo (not just the message) whenever a write fails with code 121.

Common questions

Learn more on CodeWithSQL

• SQL constraints explained

Official documentation

• MongoDB error codes (121 DocumentValidationFailure)
• Choose how to handle invalid documents
• Specify validation level for existing documents
• Query for and modify valid or invalid documents

Last technically reviewed 24 October 2026; examples and diagnostics run on MongoDB 8.0 documentation and source (error_codes.yml r8.0.0); not run locally. Codes and code names are checked against MongoDB's error_codes.yml (8.0); no MongoDB server was available, so the examples were not run locally.