mongoose-unique-validator is a plugin which adds pre-save validation for unique fields within a Mongoose schema.

This makes error handling much easier, since you will get a Mongoose validation error when you attempt to violate a unique constraint, rather than an E11000 error from MongoDB.

• Installation
• Quick Start
• Find + Updates
• Custom Error Types
• Custom Error Messages
• Custom Error Codes
• Global Defaults
• Case Insensitive
• Additional Conditions
• Caveats

npm install mongoose-unique-validator
# or
yarn add mongoose-unique-validator
# or
pnpm add mongoose-unique-validator

Apply the plugin to your schema:

import mongoose from 'mongoose'
import uniqueValidator from 'mongoose-unique-validator'

const userSchema = mongoose.Schema({
  username: { type: String, required: true, unique: true },
  email: { type: String, index: true, unique: true, required: true },
  password: { type: String, required: true }
})

userSchema.plugin(uniqueValidator)

Now when you try to save a duplicate, the error is reported as a standard Mongoose ValidationError:

try {
  const user = new User({
    username: 'JohnSmith',
    email: 'john.smith@gmail.com',
    password: 'j0hnNYb0i'
  })

  await user.save()
} catch (err) {
  // err.name === 'ValidationError'
}

{
    message: 'Validation failed',
    name: 'ValidationError',
    errors: {
        username: {
            message: 'Error, expected `username` to be unique. Value: `JohnSmith`',
            name: 'ValidatorError',
            kind: 'unique',
            path: 'username',
            value: 'JohnSmith'
        }
    }
}

findOneAndUpdate and related methods don't run validation by default. Pass { runValidators: true, context: 'query' } to enable it:

User.findOneAndUpdate(
  { email: 'old-email@example.com' },
  { email: 'new-email@example.com' },
  { runValidators: true, context: 'query' },
  function (err) {
    // ...
  }
)

context: 'query' is required — without it this plugin cannot access the update values.

Pass a type option to control the kind field on the ValidatorError:

userSchema.plugin(uniqueValidator, { type: 'mongoose-unique-validator' })

{
    errors: {
        username: {
            kind: 'mongoose-unique-validator',  // <--
            ...
        }
    }
}

You can also set this globally — see Global Defaults.

Pass a message option to customize the error message. The following template variables are available:

• {PATH} — the field name
• {VALUE} — the duplicate value
• {TYPE} — the error kind

userSchema.plugin(uniqueValidator, {
  message: 'Error, expected {PATH} to be unique.'
})

You can also set this globally — see Global Defaults.

Pass a code option to attach a numeric or string code to each ValidatorError:

userSchema.plugin(uniqueValidator, { code: 11000 })

The code is available under properties.code:

{
    errors: {
        username: {
            properties: {
                code: 11000  // <--
            },
            ...
        }
    }
}

You can also set this globally — see Global Defaults.

Instead of passing options to every schema.plugin(uniqueValidator, ...) call, set defaults once at startup. Per-schema options always take precedence.

import uniqueValidator from 'mongoose-unique-validator'

uniqueValidator.defaults.type = 'mongoose-unique-validator'
uniqueValidator.defaults.message = 'Error, expected {PATH} to be unique.'
uniqueValidator.defaults.code = 11000

Add uniqueCaseInsensitive: true to a field to treat values as case-insensitively equal. For example, john.smith@gmail.com and John.Smith@gmail.com will be considered duplicates.

const userSchema = mongoose.Schema({
  username: { type: String, required: true, unique: true },
  email: {
    type: String,
    index: true,
    unique: true,
    required: true,
    uniqueCaseInsensitive: true
  },
  password: { type: String, required: true }
})

Use MongoDB's partialFilterExpression to scope the uniqueness constraint. For example, to only enforce uniqueness among non-deleted records:

const userSchema = mongoose.Schema({
  username: { type: String, required: true, unique: true },
  email: {
    type: String,
    required: true,
    index: {
      unique: true,
      partialFilterExpression: { deleted: false }
    }
  },
  password: { type: String, required: true }
})

Note: index must be an object containing unique: true — shorthand like index: true, unique: true will cause partialFilterExpression to be ignored.

This plugin validates uniqueness by querying the database before save. Because two saves can run concurrently, both can read a count of zero and then both proceed to insert — resulting in a duplicate that MongoDB's unique index will reject with a raw E11000 error rather than a Mongoose ValidationError.

This plugin is therefore a UX layer, not a correctness guarantee. The unique index on the MongoDB collection remains the true enforcement mechanism and should always be kept in place. For most applications the race window is negligible, but in high-concurrency write scenarios be aware that the E11000 path is still reachable.