{"record":{"id":"eb05c3cc80724d92","repo":"Automattic/mongoose","slug":"must-provide-autoencryption-when-connecting-with","errorCode":null,"errorMessage":"Must provide `autoEncryption` when connecting with encrypted schemas.","messagePattern":"Must provide `autoEncryption` when connecting with encrypted schemas\\.","errorType":"exception","errorClass":"Error","httpStatus":null,"severity":"critical","filePath":"lib/drivers/node-mongodb-native/connection.js","lineNumber":322,"sourceCode":"\n  this._connectionOptions = options;\n  const dbName = options.dbName;\n  if (dbName != null) {\n    this.$dbName = dbName;\n  }\n  delete options.dbName;\n\n  if (!utils.hasUserDefinedProperty(options, 'driverInfo')) {\n    options.driverInfo = {\n      name: 'Mongoose',\n      version: pkg.version\n    };\n  }\n\n  const { schemaMap, encryptedFieldsMap } = this._buildEncryptionSchemas();\n\n  if ((utils.hasOwnKeys(schemaMap) || utils.hasOwnKeys(encryptedFieldsMap)) && !options.autoEncryption) {\n    throw new Error('Must provide `autoEncryption` when connecting with encrypted schemas.');\n  }\n\n  if (utils.hasOwnKeys(schemaMap)) {\n    options.autoEncryption.schemaMap = schemaMap;\n  }\n\n  if (utils.hasOwnKeys(encryptedFieldsMap)) {\n    options.autoEncryption.encryptedFieldsMap = encryptedFieldsMap;\n  }\n\n  this.readyState = STATES.connecting;\n  this._connectionString = uri;\n\n  let client;\n  try {\n    client = new mongodb.MongoClient(uri, options);\n  } catch (error) {\n    this.readyState = STATES.disconnected;","sourceCodeStart":304,"sourceCodeEnd":340,"githubUrl":"https://github.com/Automattic/mongoose/blob/49cdab01366679723b487ecb754b38570f783289/lib/drivers/node-mongodb-native/connection.js#L304-L340","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","solutions":["Pass autoEncryption options: mongoose.connect(uri, { autoEncryption: { keyVaultNamespace: 'encryption.__keyVault', kmsProviders: { local: { key } } } }).","Verify keyVaultNamespace and kmsProviders load correctly in every environment (they are often secret-backed).","If encryption was added to schemas unintentionally, remove the encrypted field configuration from the schemas."],"exampleFix":"// before\nconst schema = new Schema({ ssn: { type: String, encrypted: true } });\nmongoose.model('Person', schema);\nawait mongoose.connect(uri); // throws: encrypted schemas need autoEncryption\n\n// after\nawait mongoose.connect(uri, {\n  autoEncryption: {\n    keyVaultNamespace: 'encryption.__keyVault',\n    kmsProviders: { local: { key: localMasterKey } }\n  }\n});","handlingStrategy":"validation","validationCode":"// fail fast in config instead of inside connect()\nfunction assertEncryptionOpts(opts) {\n  if (opts.autoEncryption == null) {\n    throw new Error('autoEncryption options are required for this deployment (encrypted schemas are registered)');\n  }\n  const { keyVaultNamespace, kmsProviders } = opts.autoEncryption;\n  if (!keyVaultNamespace || !kmsProviders || Object.keys(kmsProviders).length === 0) {\n    throw new Error('autoEncryption requires keyVaultNamespace and kmsProviders');\n  }\n}\nassertEncryptionOpts(connectOpts);\nawait mongoose.connect(uri, connectOpts);","typeGuard":null,"tryCatchPattern":null,"preventionTips":["Keep encryption config in one module and validate it at startup for every environment that registers encrypted schemas.","Source kmsProviders from the secret manager and assert presence before connect, never fall back to plaintext.","Add a test that connects with the encrypted models compiled so schema/driver config drift fails CI."],"tags":["mongoose","csfle","queryable-encryption","autoencryption","security","mongodb"],"backgroundTag":"client-side-encryption-misconfigured","analyzedSha":"49cdab01366679723b487ecb754b38570f783289","analyzedAt":"2026-08-21T22:54:00.882Z","schemaVersion":2},"datasetVersion":"2026-08-21T23:17:16.201Z"}