Automattic/mongoose · critical · Error

Must provide `autoEncryption` when connecting with encrypted

Error message

Must provide `autoEncryption` when connecting with encrypted schemas.

What it means

When any model schema on a connection declares encrypted fields (CSFLE schema-level encryption or Queryable Encryption), the MongoDB driver must be configured with autoEncryption. During connect, Mongoose builds schemaMap/encryptedFieldsMap from those schemas and throws a plain Error if any encryption mapping exists but the connect options lack autoEncryption - otherwise the driver would silently send plaintext.

Source

Thrown at lib/drivers/node-mongodb-native/connection.js:322

  this._connectionOptions = options;
  const dbName = options.dbName;
  if (dbName != null) {
    this.$dbName = dbName;
  }
  delete options.dbName;

  if (!utils.hasUserDefinedProperty(options, 'driverInfo')) {
    options.driverInfo = {
      name: 'Mongoose',
      version: pkg.version
    };
  }

  const { schemaMap, encryptedFieldsMap } = this._buildEncryptionSchemas();

  if ((utils.hasOwnKeys(schemaMap) || utils.hasOwnKeys(encryptedFieldsMap)) && !options.autoEncryption) {
    throw new Error('Must provide `autoEncryption` when connecting with encrypted schemas.');
  }

  if (utils.hasOwnKeys(schemaMap)) {
    options.autoEncryption.schemaMap = schemaMap;
  }

  if (utils.hasOwnKeys(encryptedFieldsMap)) {
    options.autoEncryption.encryptedFieldsMap = encryptedFieldsMap;
  }

  this.readyState = STATES.connecting;
  this._connectionString = uri;

  let client;
  try {
    client = new mongodb.MongoClient(uri, options);
  } catch (error) {
    this.readyState = STATES.disconnected;

View on GitHub (pinned to 49cdab0136)

Solutions

1. Pass autoEncryption options: mongoose.connect(uri, { autoEncryption: { keyVaultNamespace: 'encryption.__keyVault', kmsProviders: { local: { key } } } }).
2. Verify keyVaultNamespace and kmsProviders load correctly in every environment (they are often secret-backed).
3. If encryption was added to schemas unintentionally, remove the encrypted field configuration from the schemas.

Example fix

// before
const schema = new Schema({ ssn: { type: String, encrypted: true } });
mongoose.model('Person', schema);
await mongoose.connect(uri); // throws: encrypted schemas need autoEncryption

// after
await mongoose.connect(uri, {
  autoEncryption: {
    keyVaultNamespace: 'encryption.__keyVault',
    kmsProviders: { local: { key: localMasterKey } }
  }
});

// fail fast in config instead of inside connect()
function assertEncryptionOpts(opts) {
  if (opts.autoEncryption == null) {
    throw new Error('autoEncryption options are required for this deployment (encrypted schemas are registered)');
  }
  const { keyVaultNamespace, kmsProviders } = opts.autoEncryption;
  if (!keyVaultNamespace || !kmsProviders || Object.keys(kmsProviders).length === 0) {
    throw new Error('autoEncryption requires keyVaultNamespace and kmsProviders');
  }
}
assertEncryptionOpts(connectOpts);
await mongoose.connect(uri, connectOpts);

When it happens

Trigger: Defining a schema with encrypted fields (e.g. paths configured with encrypted: true / encryptedFields per the Mongoose CSFLE tutorial) and then calling mongoose.connect(uri) or createConnection without autoEncryption: { keyVaultNamespace, kmsProviders } in the options.

Common situations: Incremental CSFLE/QE adoption: schemas updated first, driver options forgotten; kmsProviders config loaded from a secret manager that returned nothing; local dev without the crypt shared library configured.

Related errors

• Cannot have duplicate keys in discriminators with encryption
• Invalid sort() argument. Must be a string or object.
• ${key} is not allowed with sanitizeFilter
• Cannot call `create()` with a session and multiple documents
• Cannot create use schema for property "${path}" because the

AI-assisted analysis of Automattic/mongoose@49cdab0136 (2026-08-21). Data as JSON: /api/errors/eb05c3cc80724d92. Report an issue: GitHub.