Release Notes for MongoDB 8.3

8.3.1 - May 4, 2026

• SERVER-124974 Ensure memory lifetime during $match pushdown analysis

• All JIRA issues closed in 8.3.1

• 8.3.1 Changelog

Accessing Array Element Indexes in $map, $filter, and $reduce

MongoDB 8.3 improves access to array element indexes in $map, $filter, and $reduce aggregation expressions. You can use the new arrayIndexAs field to set a variable to store the index of an array element. You can also use the new $$IDX aggregation system variable to access the index of the current array element if you omit arrayIndexAs.

FTDC Statistics

Starting in MongoDB 8.3, Full Time Diagnostic Data Capture (FTDC) collects connPoolStats metrics for mongod processes.

serverStatus Output

serverStatus includes the following new fields in its output:

• aggregate.withExtension sub-field in metrics.commands.aggregate, tracking success and failure counts

• shardingStatistics.databaseCriticalSectionStatistics

• shardingStatistics.collectionCriticalSectionStatistics

• shardingStatistics.databaseVersionUpdateCounters

• metrics.ttl.deletedKeys

• metrics.ttl.durationMicros

• metrics.ttl.examinedDocuments

• metrics.ttl.examinedKeys

• metrics.extension

• metrics.extension.totalAggStageExecMicros

• metrics.extension.apiCallSuccesses

• metrics.extension.apiCallFailures

• metrics.extension.vectorSearch

• metrics.extension.vectorSearch.legacyVectorSearchUsed

• metrics.extension.vectorSearch.extensionVectorSearchUsed

• metrics.extension.vectorSearch.onViewKickbackRetries

• metrics.extension.vectorSearch.inSubpipelineKickbackRetries

• metrics.repl.network.oplogFetcherLagSeconds

• metrics.repl.network.oplogGetMoresProcessed

• queues.execution.admissions

• queues.execution.backgroundTasksDeprioritization

• queues.execution.deprioritizationGate

• queues.execution.heuristicDeprioritization

• queues.execution.heuristicDeprioritizationThreshold

• queues.execution.totalDeprioritizations

• queues.execution.usesPrioritization

• queues.execution.usesThroughputProbing

• queues.execution.nonDeprioritizable

• queues.execution.deprioritizable

• queues.execution.read.normalPriority.totalDelinquentAcquisitions

• queues.execution.read.normalPriority.totalAcquisitionDelinquencyMillis

• queues.execution.read.normalPriority.maxAcquisitionDelinquencyMillis

• queues.execution.read.lowPriority

MongoDB 8.3 removes the service field in the serverStatus output.

Starting in MongoDB 8.3, you can exclude all optional fields from the serverStatus output by specifying none: 1. After you exclude all optional fields, you can then specify the fields you want to include.

For details, see Exclude All Optional Fields.

You can also optionally specify lockContentionMetrics: 1 in the serverStatus command to include lockContentionMetrics in the output.

String Conversion Enhancements

Starting in MongoDB 8.3, $toString can convert additional BSON types to strings, including objects, arrays, regular expressions, MaxKeys, MinKeys, and timestamps. For details, see $toString.

MongoDB 8.3 introduces the optional base argument for $convert to convert between string and numeric values using bases 2, 8, 10, and 16. For details, see $convert.

Array Conversion Enhancements

Starting in MongoDB 8.3, you can convert strings that represent arrays using $convert or the shorthand expression $toArray.

You can also convert between binData and arrays of numeric values. For details, see Convert binData to Array and Convert an Array of Numeric Values to binData.

Object Conversion Enhancements

Starting in MongoDB 8.3, you can convert strings that represent objects using $convert or the shorthand expression $toObject.

Geospatial Index Generation

Starting in MongoDB 8.3, if a document contains both GeoJSON and legacy numeric coordinate fields, geospatial index generation prioritizes GeoJSON coordinates.

If your documents contain legacy numeric coordinate values that precede GeoJSON coordinates and existing indexes rely on that behavior, you might need to rebuild your geospatial indexes.

This change may require you to rebuild geospatial indexes if your documents contain legacy numeric coordinate values that precede GeoJSON coordinates and existing indexes rely on that behavior. Review geospatial queries to confirm they return expected results.

Remove Shard Changes

Starting in MongoDB 8.3, the removeShard command is deprecated. This release introduces four new commands to replace removeShard and provide granular control over the shard draining and removal process.

• startShardDraining

• stopShardDraining

• shardDrainingStatus

• commitShardRemoval

MongoDB provides four additional commands to transition from an embedded config server to a dedicated config server.

• startTransitionToDedicatedConfigServer

• stopTransitionToDedicatedConfigServer

• getTransitionToDedicatedConfigServerStatus

• commitTransitionToDedicatedConfigServer

PreAuth Connection Limit Parameters

MongoDB 8.3 adds three new server parameters that limit the resource consumption of pre-auth connections:

• capMemoryConsumptionForPreAuthBuffers

• messageSizeErrorRateSec

• preAuthMaximumMessageSizeBytes

cachePressureQueryPeriodMilliseconds Parameter

MongoDB 8.3 adds the cachePressureQueryPeriodMilliseconds parameter which sets the time interval MongoDB waits between checks for storage engine cache pressure. If the storage engine is under cache pressure, MongoDB aborts the oldest transaction. For details, see cachePressureQueryPeriodMilliseconds.

diagnosticDataCollectionDirectorySizeMB Parameter

MongoDB 8.3 increases the default value of diagnosticDataCollectionDirectorySizeMB from 200 to 500 MiB.

overloadAwareServerSelectionEnabled Parameter

MongoDB 8.3 adds the overloadAwareServerSelectionEnabled parameter, which controls whether retries that target other servers in the cluster avoid members that recently returned an error labeled SystemOverloadedError. You can enable this parameter to opt in to overload-aware retargeting.

ingressRequestRateLimiterApplicationExemptions Parameter

Starting in MongoDB 8.3, the ingressRequestRateLimiterApplicationExemptions parameter lets you specify applications to exempt from ingress request rate limiting. For details, see ingressRequestRateLimiterApplicationExemptions.

Database Profiler Parameters and Metrics

MongoDB 8.3 adds two parameters that let you control the impact that the Database Profiler has on query performance:

• internalQueryGlobalProfilingLockDeadlineMs

• internalProfilingMaxAbandonedWritesPerSecondPerDb

MongoDB 8.3 also adds two related serverStatus metrics:

• profiler.totalAbandonedWrites

• profiler.dbsPastThreshold

Retry Parameters

MongoDB 8.3 adds parameters to configure how internal server-side clients (between mongos and mongod) back off when retrying operations that fail due to overload.

• defaultClientBaseBackoffMillis

• defaultClientMaxBackoffMillis

• defaultClientRetryAttempts

• shardRetryTokenBucketCapacity

• shardRetryTokenReturnRate

BSONObjectTooLarge Code for Upsert Errors

Starting in 8.3, upsert operations that produce a BSON object that is too large return the 10334 BSONObjectTooLarge error code. In earlier versions, upsert operations that produce a BSON object that is too large return the 17419 or 17420 error codes.

validate Command Updates

Starting in 8.3, MongoDB no longer automatically enables the checkBSONConformance field in the db.collection.validate() method when full is true. Additionally, the db.collection.validate() method now checks to ensure a collection doesn't have any documents that exceed 16 MB.

New Expression $subtype

MongoDB 8.3 introduces a new $subtype expression to extract the subtype of binary data objects.

New Expressions for Extended JSON Conversion

MongoDB 8.3 introduces new aggregation expressions for converting between BSON and Extended JSON (EJSON) format:

• $serializeEJSON - Converts BSON values to Extended JSON format with type wrappers. Supports both Canonical and Relaxed Extended JSON formats.

• $deserializeEJSON - Converts Extended JSON format back to native BSON values.

These expressions can be combined with $convert to parse JSON strings, transform Extended JSON values into native BSON values, and convert back to JSON format.

New Expression $createObjectId

Starting in MongoDB 8.3, you can use $createObjectId to generate new random ObjectId() values in pipelines and expression-based updates.

New Hashing Expressions

MongoDB 8.3 introduces two new aggregation expressions for generating hashes from UTF-8 strings or binary data:

• $hash - Generates a BinData hash value from a UTF-8 string or binary data using MD5, SHA-256, or XXH64.

• $hexHash - Generates an uppercase hexadecimal string hash from a UTF-8 string or binary data using MD5, SHA-256, or XXH64.

Pre-Epoch Dates

Starting in MongoDB 8.3, if unit is not "millisecond" in $dateAdd or $dateSubtract and the input date is before ISODate("1970-01-01T00:00:00Z"), the result will be one second greater than in previous versions of MongoDB. This also affects the results of aggregations that perform time-based calculations like $setWindowFields and $densify.

Geospatial Index Generation

MongoDB 8.3, continues the behavior introduced in MongoDB 8.2. If a document contains both GeoJSON and legacy numeric coordinate fields, geospatial index generation prioritizes GeoJSON coordinates.

If your documents contain legacy numeric coordinate values that precede GeoJSON coordinates and existing indexes rely on that behavior, you might need to rebuild your geospatial indexes.

This change might require you to rebuild geospatial indexes if your documents contain legacy numeric coordinate values that precede GeoJSON coordinates and existing indexes rely on that behavior. Review geospatial queries to confirm they return expected results.

Subnormal Numbers in $convert Pipelines

Starting in MongoDB 8.3, the server is able to parse the full range of all representable double precision floating point numbers. This includes subnormal numbers where the most significant digit has leading zeroes and the exponent has the least possible value.

For details, see Subnormal Numbers.

chars Length Limit for $trim, $ltrim, and $rtrim

Starting in MongoDB 8.3, the length of the string you provide to chars is limited to 4096 characters. For details, see $trim Limitations.

Window Functions

Starting in MongoDB 8.3, you can use $mergeObjects in $setWindowFields operations.

sp.process() limit Option

Starting in MongoDB 8.3, sp.process() supports the options.limit input parameter. After sp.process() returns limit documents to your terminal, the session ends.

Text Search Spilling in Query Engine

Starting in MongoDB 8.3, the query engine limits the TextOr stage memory usage to 100 megabytes. The TextOr stage processes $text queries that read text score metadata. For example, TextOr processes queries that sort results by text score. If the TextOr stage exceeds this limit:

• If allowDiskUse is true, the stage spills intermediate results to disk.

• If allowDiskUse is false, the query fails with an exceeded memory limit error.

In earlier versions, the TextOr stage had no memory limit and consumed RAM without restrictions, risking out-of-memory (OOM) errors.

DDL Operations for Sharded Clusters Can Only Run on mongos

Starting in MongoDB 8.3, DDL operations and applyOps can only be run on a mongos for all sharded clusters.

findShardsOnConfigTimeoutMS Parameter

MongoDB 8.3 adds the findShardsOnConfigTimeoutMS parameter which sets the timeout in milliseconds for find operations against the config.shards namespace. For details, see findShardsOnConfigTimeoutMS.

config.csrs.indexes Removed

MongoDB 8.3 removes the config.csrs.indexes namespace.

2dsphereIndexVersion

Starting in MongoDB 8.3, 2dsphereIndexVersion is set to version 4 by default.

If you need to downgrade the FCV to anything below 8.3, you must first drop the 2dsphere version 4 indexes.

Shard Query Stats for mongos-Originated Queries

Starting in MongoDB 8.3, shard servers include queries that originate from mongos in their query statistics when queryStats is enabled. Previously, most queries forwarded from mongos to shards did not appear in shard-level query stats, which reduced the completeness of shard-level diagnostics.

Conversion to Sharded Clusters

Starting in MongoDB 8.3, replica sets that were previously sharded clusters cannot be converted back into replica sets.

The conversion of a sharded cluster into a replica set preserves sharding metadata from its prior deployment, including a shard identity document, which blocks it from again becoming a sharded cluster. If you attempt a self-managed conversion back into a sharded cluster, MongoDB returns an error.

To convert such replica sets into sharded clusters, contact Technical Support.

Conversion to Embedded Config Shard

MongoDB 8.3 introduces the mongod --replicaSetConfigShardMaintenanceMode option.

In previous releases, converting a replica set to a sharded cluster with an embedded config shard required you to first migrate to a sharded cluster with a dedicated config server replica set.

If you restart a replica set with the --replicaSetConfigShardMaintenanceMode and --configsvr options, you can convert the primary node directly into an embedded config shard.

For more information, see Convert Replica Set to an Embedded Config Shard.

refineCollectionShardKey Formatting

Starting in MongoDB 8.3, refineCollectionShardKey for time-series collections only accepts shard keys specified using the collection's logical meta and time fields. MongoDB no longer supports specifying keys using the underlying buckets format.

Index Naming Restrictions

Starting in MongoDB 8.3, creating an index with the name of "_id_" or specifying a hint of "_id_" on time series collections returns an error.

timeField Naming Restrictions

Starting in MongoDB 8.3, you cannot create a timeField that starts with a $ character.

Fields to Track Use of Memory by Queries

Starting in MongoDB 8.3, you can use the following new fields to track query memory use:

Both fields appear in the following places:

• $currentOp (Aggregation Stage) output

• db.currentOp() output

• Database profiler output

• Log messages

• Slow query log messages

The peakTrackedMemBytes field also appears in the following places:

• Explain results

• PlanCache.list() output

• $planCacheStats output

Starting in 8.3, use the following new metrics in $queryStats to measure the behavior of checkForInterrupt:

• metrics.numInterruptChecksPerSec

• metrics.overdueInterruptApproxMaxMillis

Mongos Query Shape Field

Starting in MongoDB 8.3, slow query log entries have an optional originalQueryShapeHash field that contains that query shape of the following operations that originate on the mongos :

• find

• aggregate

• count

• distinct

Slow In-Progress Query Logs

MongoDB 8.3 introduces slow in-progress query log entries. Log messages on slow in-progress queries contain less information than standard slow query logs. MongoDB logs queries at most once if the query's duration surpasses the slowOpInProgressThreshold. You can set the threshold with db.setProfilingLevel() or the new mongod --defaultSlowInProgMS command line option.

Sharded Clusters

Starting in MongoDB 8.3, if you run explain() against a database that does not exist on a sharded cluster, the execution stage reaches the end-of-stream and the operation does not create the database. For more information on end-of-stream execution stats, see explain.executionStats.executionStages.isEOF.

SCRAM-SHA-1 and FIPS Mode

Starting in MongoDB 8.3, you cannot specify SCRAM-SHA-1 for authenticationMechanisms while also specifying mongod --tlsFIPSMode or mongos --tlsFIPSMode.

If you try to specify SCRAM-SHA-1 for authenticationMechanisms while also specifying --tlsFIPSMode, the server throws an error and logs a message similar to the following:

SCRAM-SHA-1 is not allowed in FIPS mode.

Only Single-Version Downgrades are Supported

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

• For any versions, major or minor, you can upgrade or downgrade to its adjacent neighbors. For example, you can downgrade from 8.3 to 8.2 or upgrade from 7.0 to 8.0.

• For all versions, major or minor, you can downgrade to the immediately previous major version. For example, from 8.3 to 8.0.

• For any minor version, you can upgrade to the immediately next version. For example, from 8.2 to 8.3.

Backward-Incompatible Features

MongoDB 8.3 includes features that are not compatible with earlier releases. Downgrading from 8.3 to an earlier release requires that you remove data that uses these features.

For more information, see Backward-Incompatible Features.