Database Manual / Release Notes

Release Notes for MongoDB 8.2

This page describes changes and new features introduced in MongoDB 8.2.

MongoDB 8.2 is a minor Release, which means that it is supported for both MongoDB Atlas and on-premises deployments. MongoDB 8.2 introduces incremental improvements within a Major version release cycle. MongoDB 8.2 also includes changes introduced in MongoDB 8.1. This page describes changes introduced in the minor release and MongoDB 8.2.

To learn more about the differences between Major and minor releases, see MongoDB Versioning.

Important

MongoDB 8.3 is the latest minor release. Starting with MongoDB 8.2, minor releases are available for on-premises deployments (Community and EA) for specific use cases. For more information, see MongoDB Versioning.

To install the latest MongoDB version supported for on-premises use, see the installation instructions.

Important

mongosync is not supported in MongoDB 8.3.

Patch Releases

8.2.1 - Oct 3, 2025

Issues fixed:

Sharding

terminateSecondaryReadsOnOrphanCleanup Parameter

MongoDB 8.2 adds the terminateSecondaryReadsOnOrphanCleanup parameter, which controls whether long-running read operations on secondary nodes automatically terminate before orphaned document deletion following a chunk migration.

By default, this parameter is set to true. If a read operation on a secondary node begins before the chunk migration commits, MongoDB automatically terminates the operation before deleting the orphaned documents. In MongoDB versions before 8.2, these operations continue executing after orphaned document deletion and may silently miss documents without returning an error.

To support this new behavior, the default value for orphanCleanupDelaySecs is now 3600 (previously 900).

General Changes

Index Builds During Initial Sync

Starting in MongoDB 8.2, index builds during initial sync use 10% of available RAM by default. You can specify a different percentage of memory for MongoDB to use with the initialSyncIndexBuildMemoryPercentage parameter.

By default, the amount of available memory must be between 200 MB and 16 GB, inclusive. You use the following parameters to specify different minimum and maximum thresholds for memory usage:

Query Statistics

Starting in MongoDB 8.2, the $queryStats output includes the following metrics on delinquent tickets:

  • metrics.delinquentAcquisitions
  • metrics.totalAcquisitionDelinquencyMillis
  • metrics.maxAcquisitionDelinquencyMillis

MongoDB considers an execution ticket as delinquent when acquisition takes too long.

WiredTiger Cache Size Configuration as a Percentage

Starting in MongoDB 8.2, you can configure the WiredTiger internal cache size using a new percentage-based option. In addition to the existing --wiredTigerCacheSizeGB and storage.wiredTiger.engineConfig.cacheSizeGB gigabyte-based settings, you can now specify the cache size as a percentage of the available memory with the --wiredTigerCacheSizePct and storage.wiredTiger.engineConfig.cacheSizePct options.

New Inconsistency Type: Range Deletion Missing Shard Key Index

Starting in MonogDB 8.2, a new inconsistency type RangeDeletionMissingShardKeyIndex is implemented. The inconsistency type indicates that a sharded collection exists that doesn't have an index compatible with the collection shard key and there is at least one remaining range deletion task to complete.

New Aggregation Expression

Starting in MongoDB 8.2, you can use $currentDate with aggregate() to return the current time on the server.

New $currentOp Field

The $currentOp aggregation stage now includes the versionContext field, which provides information on the Feature Compatibility Version (FCV) of the operation.

serverStatus Output Change

serverStatus includes the following new fields in its output:

Explain Output for Disk Spilling Stages

Starting in MongoDB 8.2, the Explain Results for stages that spill to disk now include standardized metrics under consistent field names. This update provides a more unified way to track disk usage for memory-intensive operations.

The new fields include:

Repair Mode Field in Validation Output

Starting in MongoDB 8.2, the validate command and the db.collection.validate() helper method return a new repairMode field that indicates what types of data inconsistencies the validate command attempted to repair, if detected.

Support for zstd Fast Compression

Starting in MongoDB 8.2, The storage.wiredTiger.engineConfig.zstdCompressionLevel setting supports negative values for fast zstd compression. Negative values provide faster compression and decompression speeds at the cost of the compression ratio. The new supported range is -7 to 22.

Targeted Mirrored Reads

Starting in MongoDB 8.2, you can selectively mirror read operations to specific servers that need their caches warmed up by tagging the nodes for read mirroring. Unlike general mirrored reads, targeted read mirroring allows you to target hidden nodes and mirror from both primary and secondary nodes.

You can configure targeted mirrored reads using the targetedMirroring field in the mirrorReads parameter.

Rate Limit Ingress Connection Establishment

Starting in MongoDB 8.2, you can enable rate limiting for ingress connections to preserve CPU resources during overload. When enabled, you can see when the rate of incoming connections exceeds the connection establishment rate they specified and configure parameters to specify how your MongoDB deployment handles excess connections.

You can configure rate limiting using the following new fields:

Security

Queryable Encryption Prefix, Suffix, and Substring Query Public Preview

Warning

Prefix, Suffix, and Substring Queries are in Public Preview

Queryable Encryption prefix, suffix, and substring queries are available in public preview in MongoDB 8.2. Do not enable these query types in production. Public preview functionality will be incompatible with the GA feature, and you will have to drop any collections that enable these queries.

MongoDB 8.2 lets you enable prefix, suffix, and substring queries on encrypted string fields in Queryable Encryption enabled collections. For details, see enable substring queries and Supported Aggregation Expressions.

Known Issues

This section describes known issues in MongoDB 8.2 and their resolution status.

In VersionIssueStatus

8.2.0

SERVER-106469: The mongocryptd, mongod, and mongos processes do not start on Windows when launched with the --logpath NUL argument. A third-party dependency mistakenly disallows the use of NUL, resulting in this log file path preventing mongocryptd from starting. MongoDB drivers may fail to start mongocryptd successfully on Windows if --logpath NUL is specified. The MongoDB .NET/C# Driver uses --logpath NUL in its default configuration and will fail to start on Windows.

You can avoid the .NET/C# Driver mongocryptd issue in the following ways:

We are targeting a fix for this issue in MongoDB 8.2.1.

8.2.0

SERVER-109626: v8.2.0 introduces some change stream performance regressions. Applications relying on change streams for real-time data processing may experience up to a 15% performance degradation compared to v8.0.

We are targeting a fix for this issue in MongoDB 8.2.1.

8.2.0

SERVER-110250: Users running memory-intensive operations that require disk spilling can experience server crashes if the number of actively spilling queries exceeds 1000. To mitigate this issue, raise the spillWiredTigerSessionMax setParameter value to a higher value.

We are targeting a fix for this issue in MongoDB 8.2.1.

Changes Introduced in MongoDB 8.1

The following section describes changes and new features introduced in MongoDB 8.1.

Add Comments to Query Settings

Starting in MongoDB 8.1 (and 8.0.4), you can use setQuerySettings to add comments to query settings. For example, add a comment that indicates why you added query settings.

Aggregation Accumulators

Starting in MongoDB 8.1, the following aggregation accumulators are available:

Aggregation Stages

Starting in MongoDB 8.1, the following aggregation stages are available:

Audit Log Improvements

Starting in MongoDB 8.1, if a client application connects to mongos through a load balancer, the origin client computer and load balancer IP addresses and ports are included in the audit log. You can use the log to match an audit event with the origin client computer.

For details, see OCSF Schema Audit Messages and mongo Schema Audit Messages.

connectionStatus Connection UUID

Starting in MongoDB 8.1, you can access the currently connected client's UUID through connectionStatus.authInfo.UUID.

Disk Space

Starting in MongoDB 8.1 (and 8.0.5), if disk space is running low, MongoDB will fail queries that are spilling to disk.

$geoNear Improvements

Starting in MongoDB 8.1, some previously failing $geoNear queries with hidden 2d or 2dsphere indexes will now succeed. In previous releases, some $geoNear queries used to unnecessarily fail with an IndexNotFound error when they included a hidden index due to confusion over which index to use.

Improved Accuracy for Operation Duration Metric

Starting in MongoDB 8.1, the durationMillis metric reported in slow query logs accounts for time spent processing authorization and parsing the command. As a result, durationMillis more closely reflects the full command duration.

Inconsistency Types

Starting in MongoDB 8.1, the following inconsistency types are available:

$lookup Support for Encrypted Collections

Starting in MongoDB 8.1, you can reference multiple encrypted collections in a $lookup stage.

To learn more, see:

$merge Missing Fields

Starting in MongoDB 8.1, if the $merge aggregation stage's supporting index is not sparse, the fields specified for the on option can be missing or contain a null value.

Query Statistics

Starting in MongoDB 8.1, query statistics are collected and reported for count and distinct commands. For details, see count Command Query Shape and distinct Command Query Shape.

Server Parameters

Starting in MongoDB 8.1, the following server parameters are available:

serverStatus Metrics

Starting in MongoDB 8.1 (and 8.0.4 and 7.0.14), the indexStats section of the serverStatus command output tracks indexes in prepareUnique state.

MongoDB 8.1 adds the following server status metrics:

Slow Query Metrics for Disk Spilling

Starting in MongoDB 8.1, log messages for slow queries contain new metrics if the query execution writes temporary files to disk. These metrics are prefixed by the query execution stage that caused the query to exceed the memory limit. For example, sortSpills indicates the number of times that the sort stage of query execution wrote temporary files to disk.

MetricDescription

<executionPart>Spills

Number of times the corresponding query execution stage wrote temporary files to disk

<executionPart>SpilledBytes

Size, in bytes, of the memory released by writing temporary files to disk

<executionPart>SpilledDataStorageSize

Size, in bytes, of disk space used for temporary files

<executionPart>SpilledRecords

Number of records written to temporary files on disk

For more information on writing temporary files to disk, see allowDiskUse().

Stable API

Starting in MongoDB 8.1, the renameCollection command and corresponding shell method, db.collection.renameCollection(), are included in Stable API V1.

Support for Search Stages in Explain Results

Starting in MongoDB 8.1, the explain results include execution stats for the $search, $searchMeta, and $vectorSearch stages.

To learn more, see:

Support for Search Index Commands on Views

Starting in MongoDB 8.1, you can run createSearchIndexes, updateSearchIndex, dropSearchIndex, and $listSearchIndexes to create, modify, drop, and list Atlas Search indexes and Atlas Vector Search indexes on compatible standard views that contain only the following stages:

You can run aggregation pipelines that contain $search and $searchMeta stages on views that use a search index. You can also run aggregation pipelines that contain a $vectorSearch stage on views that contain a vector search index.

Validate Command Index Specifications Output

Starting in MongoDB 8.1, the validate command includes index specifications in the validate.indexDetails output field.

Validation Action for Handling Invalid Documents

Starting in MongoDB 8.1, you can set your schema's validationAction option to errorAndLog, in which MongoDB rejects any insert or update that violates the validation criteria and logs the error to the mongod log file.

For more information, see Choose How to Handle Invalid Documents.

Upgrade Procedures

Important

Feature Compatibility Version

To upgrade to MongoDB 8.2 from a 8.0 deployment, the 8.0 deployment must have featureCompatibilityVersion set to 8.0. To check the version:

db.adminCommand( { getParameter: 1, featureCompatibilityVersion: 1 } )

To upgrade to MongoDB 8.2, refer to the upgrade instructions specific to your MongoDB deployment:

If you need guidance on upgrading to 8.2, MongoDB professional services offer support to help ensure a smooth transition without interruption to your MongoDB application. To learn more, see MongoDB Consulting.

Download

To download MongoDB 8.2, go to the MongoDB Download Center.

Downgrade Considerations

Only Single-Version Downgrades are Supported

MongoDB only supports single-version downgrades. You cannot downgrade to a release that is multiple versions behind your current release.

For example, you can downgrade a 8.2-series to a 8.0-series deployment. However, further downgrading that 8.0-series deployment to a 7.0-series deployment is not supported.

Downgrade Policy

  • Binary downgrades aren't supported for MongoDB Community Edition.
  • You cannot downgrade your deployment's FCV to or from a minor release version of MongoDB.
  • If you upgrade or downgrade your deployment's FCV, you cannot downgrade your Enterprise deployment's binary version without assistance from support.