MongoDB NodeJS Driver Files

6.17.0 (2025-06-03)

The MongoDB Node.js team is pleased to announce version 6.17.0 of the mongodb package!

Release Notes

Support for MongoDB 4.0 is removed

[!WARNING] When the driver connects to a MongoDB server of version 4.0 or less, it will now throw an error.

OIDC machine workflows now retry on token expired errors during initial authentication

This resolves issues of a cached OIDC token in the driver causing initial authentication to fail when the token had expired. The affected environments were "azure", "gcp", and "k8s".

keepAliveInitialDelay may now be configured at the MongoClient level

When not present will default to 120 seconds. The option value must be specified in milliseconds.

:::typescript
import { MongoClient } from 'mongodb';

const client = new MongoClient(process.env.MONGODB_URI, { keepAliveInitialDelay: 100000 });

updateOne and replaceOne now support a sort option

The updateOne and replaceOne operations in each of the ways they can be performed support a sort option starting in MongoDB 8.0. The driver now supports the sort option the same way it does for find or findOneAndModify-style commands:

:::js
const sort = { fieldName: -1 };

collection.updateOne({}, {}, { sort });
collection.replaceOne({}, {}, { sort });

collection.bulkWrite([ 
  { updateOne: { filter: {}, update: {}, sort } },
  { replaceOne: { filter: {}, replacement: {}, sort } },
]);

client.bulkWrite([
  { name: 'updateOne', namespace: 'db.test', filter: {}, update: {}, sort },
  { name: 'replaceOne', namespace: 'db.test', filter: {}, replacement: {}, sort }
]);

MongoClient close shuts outstanding in-use connections

The MongoClient.close() method now shuts connections that are in-use allowing the event loop to close if the only remaining resource was the MongoClient.

Support Added for Configuring the DEK cache expiration time.

Default value is 60000. Requires using mongodb-client-encryption >= 6.4.0

For ClientEncryption:

:::ts
import { MongoClient, ClientEncryption } from 'mongodb';
const client = new MongoClient(process.env.MONGODB_URI);
const clientEncryption = new ClientEncryption(client, { keyExpirationMS: 100000, kmsProviders: ... });

For auto encryption:

:::ts
import { MongoClient, ClientEncryption } from 'mongodb';
const client = new MongoClient(process.env.MONGODB_URI, {
  autoEncryption: {
    keyExpirationMS: 100000,
    kmsProviders: ...
  }
});

Update operations will now throw if ignoreUndefined is true and all operations are undefined.

When using any of the following operations they will now throw if all atomic operations in the update are undefined and the ignoreUndefined option is true. This is to avoid accidental replacement of the entire document with an empty document. Examples of this scenario:

:::typescript
import { MongoClient } from 'mongodb';

const client = new MongoClient(process.env.MONGODB_URI);

client.bulkWrite(
  [
    {
      name: 'updateMany',
      namespace: 'foo.bar',
      filter: { age: { $lte: 5 } },
      update: { $set: undefined, $unset: undefined }
    }
  ],
  { ignoreUndefined: true }
);

const collection = client.db('test').collection('test');

collection.bulkWrite(
  [
    {
      updateMany: {
        filter: { age: { $lte: 5 } },
        update: { $set: undefined, $unset: undefined }
      }
    }
  ],
  { ignoreUndefined: true }
);

collection.findOneAndUpdate(
  { a: 1 },
  { $set: undefined, $unset: undefined },
  { ignoreUndefined: true }
);

collection.updateOne({ a: 1 }, { $set: undefined, $unset: undefined }, { ignoreUndefined: true });

collection.updateMany({ a: 1 }, { $set: undefined, $unset: undefined }, { ignoreUndefined: true });

Socket errors are always treated as network errors

Network errors perform an important role in the driver, impacting topology monitoring processes and retryablity. A bug in the driver's socket implementation meant that in scenarios where server disconnects occurred while no operation was in progress on the socket resulted in errors that were not considered network errors.

Socket errors are now unconditionally treated as network errors.

Features

• NODE-6245: add keepAliveInitialDelay config (#4510) (d6c0eb3)
• NODE-6290: add sort support to updateOne and replaceOne (#4515) (28857b7)
• NODE-6882: eagerly close checked out connections when client is closed (#4499) (64fdb3e)
• NODE-6884: remove support for 4.0 (#4534) (6fe6ccc)
• NODE-6952: support configuring DEK cache expiration (#4538) (c529f07)
• NODE-6963: use BSON 6.10.4 (#4549) (aee490a)

Bug Fixes

• NODE-6638: throw if all atomic updates are undefined (#4519) (9625b2d)
• NODE-6864: socket errors are not always converted to MongoNetworkErrors (#4473) (2d86095)
• NODE-6962: OIDC machine workflows use OIDCCallbacks internally (#4546) (bd6030f)

Documentation

• Reference
• API
• Changelog

We invite you to try the mongodb library immediately, and report any issues to the NODE project.