/ /

Compatibility Changes in MongoDB 5.0

This version of the documentation is archived and no longer supported. To upgrade your 6.0 deployment, see the MongoDB 7.0 upgrade procedures.

The following 5.0 changes can affect compatibility with older versions of MongoDB.

Certain Commands Only Accept Recognized Parameters

Starting in MongoDB 5.0, certain database commands raise an error if passed a parameter not explicitly accepted by the command. In MongoDB 4.4 and earlier, unrecognized parameters are silently ignored.

Affected Commands:

Removed Commands

Starting in MongoDB 5.0, these database commands and mongo shell helper methods are removed:

Removed Command	Alternative
`db.collection.copyTo()`	`$out`
`db.collection.ensureIndex()`	`db.collection.createIndex()`
`db.collection.save()`	`db.collection.insertOne()` `db.collection.insertMany()`
`db.resetError()`	Not available
`geoSearch`	One of the Geospatial Query Operators
`Mongo.getSecondaryOk()`	Mongo.getReadPrefMode() (mongosh method)
`Mongo.isCausalConsistency`	Not available
`Mongo.setSecondaryOk()`	Mongo.setReadPref() (mongosh method)
`rs.secondaryOk()`	Mongo.setReadPref() (mongosh method)
`resetError`	Not available
`shardConnPoolStats`	`connPoolStats`
`unsetSharding`	Not available

Removed Parameters

MongoDB 5.0 removes the following server parameters:

Removed Parameters	Description
`cachePressureThreshold`	MongoDB 5.0 removes the `cachePressureThreshold` server parameter. Due to changes in how WiredTiger calculates snapshot window size this parameter is no longer relevant.
`shouldMultiDocTxnCreateCollectionAndIndexes`	MongoDB 5.0 removes the `shouldMultiDocTxnCreateCollectionAndIndexes` server parameter. In 5.0+, collection and index creation inside of transactions is always enabled. You can no longer use the server parameter to disable this behavior.
`connPoolMaxShardedConnsPerHost`	MongoDB 5.0 removes the `connPoolMaxShardedConnsPerHost` server parameter.
`connPoolMaxShardedInUseConnsPerHost`	MongoDB 5.0 removes the `connPoolMaxShardedInUseConnsPerHost` server parameter.
`shardedConnPoolIdleTimeoutMinutes`	MongoDB 5.0 removes the `shardedConnPoolIdleTimeoutMinutes` server parameter.

Removed Index Types

MongoDB 5.0 removes the deprecated geoHaystack index. Use a 2d index instead.

Upgrading your MongoDB instance to 5.0 and setting featureCompatibilityVersion to 5.0 will delete any pre-existing geoHaystack indexes.

Removed Metrics

Starting in MongoDB 5.0, the serverStatus command does not output opReadConcernCounters, which contained the read concern level specified by query operations. Instead, the new readConcernCounters replaces opReadConcernCounters and contains additional information.

Starting in MongoDB 5.0, the serverStatus command does not output the cache pressure percentage threshold and the current cache pressure percentage under wiredTiger.snapshot-window-settings.

`currentOp` Output Change

Starting in MongoDB 5.0, the $currentOp.remainingOperationTimeEstimated metric is only present on the recipient shard when a resharding operation is taking place.

Removed Raspberry Pi Support

MongoDB 5.0 removes support for Raspberry Pi. To run MongoDB on Raspberry Pi, install version 4.4.

TTL `expireAfterSeconds` Behavior When Set to `NaN`

Starting in MongoDB 5.0, TTL indexes with expireAfterSeconds set to NaN experience a behavior change compared to earlier versions.

The behavior change affects:

direct upgrades
initial sync from earlier versions
mongorestore from earlier versions

Performing any of those actions causes an expireAfterSeconds value of NaN to be treated as an expireAfterSeconds of 0. As a result, documents may expire immediately.

Starting in MongoDB 5.0.14 (and 6.0.2), the server will not use TTL indexes that have expireAfterSeconds set to NaN.

Shell Changes

The mongo shell has been deprecated in MongoDB v5.0. The replacement shell is mongosh.

Shell packaging also changes in MongoDB v5.0. Refer to the installation instructions for further details.

Replica Sets

`enableMajorityReadConcern` Is Not Configurable

Starting in MongoDB 5.0, enableMajorityReadConcern and --enableMajorityReadConcern cannot be changed and are always set to true due to storage engine improvements.

In earlier versions of MongoDB, enableMajorityReadConcern and --enableMajorityReadConcern are configurable and can be set to false to prevent storage cache pressure from immobilizing a deployment with a three-member primary-secondary-arbiter (PSA) architecture.

If you are using a three-member primary-secondary-arbiter (PSA) architecture, consider the following:

The write concern "majority" can cause performance issues if a secondary is unavailable or lagging. For advice on how to mitigate these issues, see Mitigate Performance Issues with a Self-Managed PSA Replica Set.
If you are using a global default "majority" and the write concern is less than the size of the majority, your queries may return stale (not fully replicated) data.

`secondaryDelaySecs` Configuration Setting

Starting in MongoDB 5.0, secondaryDelaySecs replaces slaveDelay. This change is not backwards compatible.

Host Names Required for Split Horizon DNS

To configure cluster nodes for split horizon DNS, use host names instead of IP addresses.

Starting in MongoDB v5.0, replSetInitiate and replSetReconfig reject configurations that use IP addresses instead of hostnames.

Use disableSplitHorizonIPCheck to modify nodes that cannot be updated to use host names. The parameter only applies to the configuration commands.

mongod and mongos do not rely on disableSplitHorizonIPCheck for validation at startup. Legacy mongod and mongos instances that use IP addresses instead of host names can start after an upgrade.

Instances that are configured with IP addresses log a warning to use host names instead of IP addresses.

Non-transactional Reads on `config.transactions`

Starting in MongoDB 5.0, non-transaction reads are not allowed on the config.transactions collection with the following read concerns and options:

"snapshot"
"majority" and the afterClusterTime option is set
When using a MongoDB Driver and "majority" within a causally consistent session

Manual Oplog Writes

Starting in MongoDB 5.0, it is no longer possible to perform manual write operations to the oplog on a cluster running as a replica set. Performing write operations to the oplog when running as a standalone instance should only be done with guidance from MongoDB Support.

Automatic Reconfiguration for New Voting Replica Set Members

Starting in MongoDB 5.0, a newly added secondary does not count as a voting member and cannot be elected until it has reached the SECONDARY state.

When a new voting node is added to a replica set, replSetReconfig will internally add a newlyAdded field to the node's configuration. Nodes with the newlyAdded field do not count towards the current number of voting nodes. When initial sync completes and the node reaches SECONDARY state, the newlyAdded field is automatically removed.

Note

Configurations that attempt to add a field named newlyAdded will error even if run with { force: true }.
If an existing node has a newlyAdded field, using rs.reconfig() to change the configuration will not remove the newlyAdded field. The newlyAdded field will be appended to the user provided configuration.
replSetGetConfig will remove any newlyAdded fields from its output. If you would like to see any newlyAdded fields, you can query the local.system.replset collection directly.

Removed Customizable Values For getLastErrorDefaults

Starting in MongoDB 5.0, you cannot specify a default write concern with settings.getLastErrorDefaults other than the default of { w: 1, wtimeout: 0 } . Instead, use the setDefaultRWConcern command to set the default read or write concern configuration for a replica set or sharded cluster.

Replica Set Write Acknowledgement

Starting in MongoDB 5.0, replica set members in the STARTUP2 state do not participate in write majorities.

Tip

Write Concern for Replica Sets

Implicit Default Write Concern

Starting in MongoDB 5.0, the implicit default write concern is w: majority. However, there is an edge case for replica set deployments containing arbiters:

The voting majority of a replica set is 1 plus half the number of voting members, rounded down. If the number of data-bearing voting members is not greater than the voting majority, the default write concern is { w: 1 }.
In all other scenarios, the default write concern is { w: "majority" }.

Specifically, MongoDB uses the following formula to determine the default write concern:

if [ (#arbiters > 0) AND (#non-arbiters <= majority(#voting-nodes)) ]
    defaultWriteConcern = { w: 1 }
else
    defaultWriteConcern = { w: "majority" }

For example, consider the following deployments and their respective default write concerns:

Non-Arbiters	Arbiters	Voting Nodes	Majority of Voting Nodes	Implicit Default Write Concern
2	1	3	2	`{ w: 1 }`
4	1	5	3	`{ w: "majority" }`

In the first example:
- There are 2 non-arbiters and 1 arbiter for a total of 3 voting nodes.
- The majority of voting nodes (1 plus half of 3, rounded down) is 2.
- The number of non-arbiters (2) is equal to the majority of voting nodes (2), resulting in an implicit write concern of { w: 1 }.
In the second example:
- There are 4 non-arbiters and 1 arbiter for a total of 5 voting nodes.
- The majority of voting nodes (1 plus half of 5, rounded down) is 3.
- The number of non-arbiters (4) is greater than the majority of voting nodes (3), resulting in an implicit write concern of { w: "majority" }.

The { w: "majority" } default write concern provides a stronger durability guarantee in the event of an election, or if replica set members become unavailable.

Read Concern `snapshot` on Capped Collections

Starting in MongoDB 5.0, you cannot use read concern "snapshot" when reading from a capped collection.

`local` is the Default Read Concern

Starting in MongoDB 5.0, "local" is the default read concern level for read operations against the primary and secondaries. In MongoDB 4.4, queries targeting sharded cluster secondaries use read concern "available" and can return orphaned documents.

This may introduce a significant latency increase for count queries that use a filter and for covered queries.

You can opt out of this behavior by setting the cluster-wide read concern with setDefaultRWConcern.

New `cursor.map()` Return Type

cursor.map() returned an Array in the legacy mongo shell. The return type is Cursor in mongosh. You can use .toArray() to convert the results.

Update Operator Changes

Starting in MongoDB 5.0, mongod no longer raises an error when you use the following update operators with an empty operand expression ( { } ):

An empty update results in no changes and no oplog entry is created (meaning that the operation is a no-op).

Update Operator Processing Order

Starting in MongoDB 5.0, update operators process document fields with string-based names in lexicographic order. Fields with numeric names are processed in numeric order. See Update Operators Behavior for details.

`$setWindowFields` Stage with Transactions and Snapshot Read Concern

In MongoDB versions earlier than 5.3, the $setWindowFields aggregation pipeline stage cannot be used with transactions or the "snapshot" read concern.

Aggregation Pipeline Operator Parameter Limits

The following aggregation pipeline operators now have a 64-bit integer value maximum limit.

If you pass a value that exceeds this limit, the pipeline returns an invalid argument error.

`listDatabases` Output Changes

Starting in MongoDB 5.0, output from the listDatabases command running against a mongod is more consistent with output from listDatabases running against a mongos.

The following table shows the differences in data types for listDatabases output fields between MongoDB 5.0 and earlier versions. Only fields which differ between 5.0 and earlier versions are listed.

Field	Type in MongoDB 5.0	Type in MongoDB 4.4 and earlier (`mongod`)	Type in MongoDB 4.4 and earlier (`mongos`)
`sizeOnDisk`	integer	double	integer
`totalSize`	integer	double	integer
`totalSizeMb`	integer	not present (see below)	integer

The output from listDatabases now includes the totalSizeMb field when run against either a mongos or a mongod. In MongoDB 4.4 and earlier, totalSizeMb only appears when run against mongos. totalSizeMb is the sum of the sizeOnDisk fields, expressed in megabytes.

When run against mongos, the shards field in the listDatabases output contains a field-value pair for each collection on a particular shard. Size values in the shards field are expressed as integers.

Security

TLS Connection X509 Certificate Startup Warning

Starting in MongoDB 5.0, mongod and mongos now issue a startup warning when their certificates do not include a Subject Alternative Name attribute.

The following platforms do not support common name validation:

iOS 13 and higher
MacOS 10.15 and higher
Go 1.15 and higher

Clients using these platforms will not authenticate to MongoDB servers that use X.509 certificates whose hostnames are specified by CommonName attributes.

Map-Reduce

Starting in version 5.0, MongoDB deprecates the map-reduce operation.

For examples of aggregation pipeline alternatives to map-reduce operations, see Map-Reduce to Aggregation Pipeline and Map-Reduce Examples.

Auditing

MongoDB 5.0 adds auditing capabilities that can be configured at runtime.

If auditLog.runtimeConfiguration is set to true, then the mongod and mongos configuration files can no longer set setParameter.auditAuthorizationSuccess or configure audit filters. If the server configuration files contain these settings the server will fail to start and will log an error.

If auditLog.runtimeConfiguration is set to false and an audit filter config document is present, then a startup warning will be issued but the server will not abort.

Reduce Risk of Stale Chunks in Sharded Transactions

Starting in MongoDB 5.0, if you change the transactionLifetimeLimitSeconds parameter, you must also change transactionLifetimeLimitSeconds to the same value on all config server replica set members. Keeping this value consistent:

Ensures the routing table history is retained for at least as long as the transaction lifetime limit on the shard replica set members.
Reduces the transaction retry frequency and therefore improves performance.

General Changes

Starting in MongoDB 5.0:

For featureCompatibilityVersion set to "5.0" or greater, users can no longer write directly to the <database>.system.views collection.
The reIndex command and the db.collection.reIndex() shell method may only be run on standalone instances.
The number of aggregation pipeline stages allowed in a single pipeline is limited to 1000.
Dropping the final collection in a database (or dropping the database itself) when directoryPerDB or --directoryperdb is enabled deletes the newly empty subdirectory for that database.
The $subtract aggregation operator will convert the data type of the result if necessary to accurately represent the result value. See $subtract for the specific conversions.
MongoDB removes the --serviceExecutor command-line option and the corresponding net.serviceExecutor configuration option.
You may not authenticate as multiple simultaneous users on the same client session if the --apiStrict option is set. Attempting to authenticate as a new user while currently logged in as an existing user when the --apiStrict option is set will generate an error message once per authentication attempt. If you are not using the --apiStrict option, authenticating as a new user while currently logged in as an existing user will write a warning to the log once per authentication attempt.
The weights option is only allowed for $text indexes.
You must explicitly set the global default write concern before attempting to reconfigure a non-sharded replica set with a configuration that would change the implicit default write concern. To set the global default write concern, use the setDefaultRWConcern command.
To set the replSetOplog size in mongosh, use the Double() constructor with the replSetResizeOplog command.

Deprecations

Deprecated	Description
`mongo`	The legacy `mongo` shell has been deprecated in MongoDB v5.0. The replacement is `mongosh`.
`db.printSlaveReplicationInfo()`	Deprecated since version 4.4.1: Use `db.printSecondaryReplicationInfo()` instead.
`rs.printSlaveReplicationInfo()`	Deprecated since version 4.4.1: Use `rs.printSecondaryReplicationInfo()` instead.
`security.clusterIpSourceWhitelist`	Deprecated in version 5.0: Use `security.clusterIpSourceAllowlist` instead.
`--clusterIpSourceWhitelist`	Deprecated in version 5.0: Use `--clusterIpSourceAllowlist` instead.
`logout`	Deprecated in version 5.0: Disconnect from the server to end your session instead.
`db.logout()`	Deprecated in version 5.0: Disconnect from the server to end your session instead.
local audit message field	Deprecated in version 5.0: Use the `localEndpoint` field in the clientMetadata audit message instead.

Deprecated Wire Protocol Opcodes

MongoDB 5.0 deprecates the following wire protocol opcodes:

OP_REPLY
OP_UPDATE
OP_INSERT
OP_QUERY
OP_GET_MORE
OP_DELETE
OP_KILL_CURSORS

Newer driver versions use OP_MSG instead of these deprecated opcodes.

The related commands and methods are also deprecated in MongoDB 5.0:

getLastError
db.getLastError()
db.getLastErrorObj()

To ensure your driver uses the most up-to-date wire protocol, upgrade your driver to a 5.0-compatible version.

Any code explicitly using getLastError, db.getLastError(), or db.getLastErrorObj() should instead use the CRUD API to issue the write with the desired write concern. Information about the success or failure of the write operation will be provided directly by the driver as a return value.

5.0 Feature Compatibility

Some features in 5.0 require not just the 5.0 binaries but the featureCompatibilityVersion (FCV) set to 5.0. These features include:

Creation of time series collections requires FCV set to 5.0+.
Configuring Runtime Audit Filter Management requires FCV set to 5.0+.
Usage of . and $ in field names requires FCV set to 5.0+.
Resharding a collection requires FCV set to 5.0+.

Back

5.0

Upgrade 4.4 to 5.0