mongodb

6.16.0 (2025-04-21)

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

Release Notes

distinct commands now support an index hint

The Collection.distinct() method now supports an optional hint, which can be used to tell the server which index to use for the command:

// providing an index description
await collection.distinct('my-key', { 
  hint: { 'my-key': 1 }
});

// providing an index name
await collection.distinct('my-key', { 
  hint: 'my-key'
});

This requires server 7.1+.

Driver support for servers <=4.0 deprecated

[!WARNING] Node driver support for server 4.0 will be removed in an upcoming minor release. Reference: MongoDB Software Lifecycle Schedules.

Fix processing of multiple messages within one network data chunk

During elections, or other scenarios where the server is pushing multiple topology updates to the driver in a short period of time, a bug in the driver's socket code led to backlog of topology updates that would remain in the buffer until another heartbeat arrived from the server. This could lead to delays in the driver recovering from an election and/or an increase in MongoServerSelectionErrors.

Now, all messages in the current buffer are returned to the driver leading to faster processing times.

Huge thank you to @andreim-brd for sharing a self-contained reproduction that proved to be instrumental in the identification of the underlying issue!

FindCursor.rewind() throws documents?.clear() is not a function errors in certain scenarios

In certain scenarios where limit and batchSize are both set on a FindCursor, an internal driver optimization intended to prevent unnecessary requests to the server when the driver knows the cursor is exhausted would prevent the cursor from being rewound. This issue has been resolved.

Features

• NODE-6494: add support for hint on distinct commands (#4487) (40d0e87)
• NODE-6515: deprecate driver support for server 4.0 (#4517) (4c1a8a7)

Bug Fixes

• NODE-6630: read all messages in buffer when chunk arrives (#4512) (8c86e30)
• NODE-6878: documents.clear() throws a TypeError after cursor is rewound (#4488) (a1fffeb)

Documentation

• Reference
• API
• Changelog

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

6.15.0 (2025-03-18)

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

Release Notes

Support for custom AWS credential providers

The driver now supports a user supplied custom AWS credentials provider for both authentication and for KMS requests when using client side encryption. The signature for the custom provider must be of () => Promise<AWSCredentials> which matches that of the official AWS SDK provider API. Provider chains from the actual AWS SDK can also be provided, allowing users to customize any of those options.

Example for authentication with a provider chain from the AWS SDK:

import { fromNodeProviderChain } from '@aws-sdk/credential-providers';

const client = new MongoClient(process.env.MONGODB_URI, {
  authMechanismProperties: {
    AWS_CREDENTIAL_PROVIDER: fromNodeProviderChain()
  }
});

Example for using a custom provider for KMS requests only:

import { fromNodeProviderChain } from '@aws-sdk/credential-providers';

const client = new MongoClient(process.env.MONGODB_URI, {
  autoEncryption: {
    keyVaultNamespace: 'keyvault.datakeys',
    kmsProviders: { aws: {} },
    credentialProviders: {
      aws: fromNodeProviderChain()
    }
  }
}

Custom providers do not need to come from the AWS SDK, they just need to be an async function that returns credentials:

const client = new MongoClient(process.env.MONGODB_URI, {
  authMechanismProperties: {
    AWS_CREDENTIAL_PROVIDER: async () => {
      return {
        accessKeyId: process.env.ACCESS_KEY_ID,
        secretAccessKey: process.env.SECRET_ACCESS_KEY
      }
    }
  }
});

Fix misc unhandled rejections under special conditions

We identified an issue with our test suite that suppressed catching unhandled rejections and surfacing them to us so we can ensure the driver handles any possible rejections. Luckily only 3 cases were identified and each was under a flagged or specialized code path that may not have been in use:

• If the MongoClient was configured to use OIDC and an AbortSignal was aborted on cursor at the same time the client was reauthenticating, if the reauth process was rejected it would have been unhandled.
• If timeoutMS was used and the timeout expired before an operation reached the server selection step the operation would throw the expected timeout error but a promise representing the timeout would also raise an unhandled rejection.
• If a change stream was closed while processing a change event it was possible for the "change stream is closed" error to be emitted as an error event and reject an internal promise representing fetching the "next" change.

Features

• NODE-6141: allow custom aws sdk config (#4373) (3d047ed)

Bug Fixes

• NODE-6845: ensure internal rejections are handled (#4448) (06e941a)

Documentation

• Reference
• API
• Changelog

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

6.14.2 (2025-03-04)

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

Release Notes

KMS Requests can cause unhandled rejection

When using explicit encryption or automatic encryption, the driver makes requests to a Key Management System when to fetch key encryption keys. The driver supports connecting to a KMS provider through a Socks5 proxy. However, the socket used for the socks5 proxy was created in all circumstances, regardless of proxy configuration. This leads to unhandled rejection errors when closing the socket the driver attempts to clean up the unused socket.

With the changes in this release, the socket is only created if a proxy is configured and the any promises created for the proxy are properly handled.

Bug Fixes

• NODE-6803: kms proxy socket creates unhandled rejection (#4444) (ed69cf9)

Documentation

• Reference
• API
• Changelog

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

6.14.1 (2025-03-03)

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

Release Notes

Fixed occasional OIDC reauthentication failure

Error code 391 is intended to make the driver internally reauthenticate the connection to the server, however, occasionally this was being raised to the user. This was due to a bug in setting the cached access token on newly created connections.

Bug Fixes

• NODE-6801: set token on connection from cache (#4438) (cb13746)

Documentation

• Reference
• API
• Changelog

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