> For the complete MongoDB documentation index, see www.mongodb.com/docs/llms.txt # setFeatureCompatibilityVersion (database command) ## Definition Enables or disables the features that persist data incompatible with earlier versions of MongoDB. You can only issue the [`setFeatureCompatibilityVersion`](https://www.mongodb.com/docs/manual/reference/command/setFeatureCompatibilityVersion.md#mongodb-dbcommand-dbcmd.setFeatureCompatibilityVersion) against the `admin` database. **Warning:** Enabling backwards-incompatible features can complicate the downgrade process since you must remove any persisted backwards-incompatible features before you downgrade. After upgrading, allow your deployment to run without enabling backwards-incompatible features for a burn-in period. Enable these features only after you are confident that a downgrade is unlikely. ## Compatibility This command is available in deployments hosted in the following environments: - [MongoDB Enterprise](https://www.mongodb.com/docs/manual/administration/install-enterprise.md#std-label-install-mdb-enterprise): The subscription-based, self-managed version of MongoDB - [MongoDB Community](https://www.mongodb.com/docs/manual/administration/install-community.md#std-label-install-mdb-community-edition): The source-available, free-to-use, and self-managed version of MongoDB ## Syntax **Changed in version 8.3** The command has the following syntax: ```javascript db.adminCommand( { setFeatureCompatibilityVersion: , confirm: true, writeConcern: { wtimeout: }, dryRun: } ) ``` ## Command Fields The `setFeatureCompatibilityVersion` command takes the following fields: ### setFeatureCompatibilityVersion *Required* The possible values for `version` are: | Version | Description | | --- | --- | | `"8.3"` | *Available on MongoDB 8.3 Deployments* Enables the [8.3 features that persist data incompatible with MongoDB 8.2.](https://www.mongodb.com/docs/manual/release-notes/8.3.md#std-label-8.3-downgrade-considerations) | | `"8.2"` | *Available on MongoDB 8.2 and MongoDB 8.3 Deployments* Starting in MongoDB 8.3, you can downgrade FCV (feature compatibility version) from `"8.3"` to `"8.2"`. | | `"8.0"` | *Available on MongoDB 8.0 Deployments* Enables the [8.0 features that persist data incompatible with MongoDB 7.0.](https://www.mongodb.com/docs/manual/release-notes/8.0.md#std-label-8.0-downgrade-considerations) | | `"7.0"` | *Available on MongoDB 7.0 Deployments* Enables the [7.0 features that persist data incompatible with MongoDB 6.0.](https://www.mongodb.com/docs/manual/release-notes/7.0.md#std-label-7.0-downgrade-considerations) | ### confirm *Required* **New in version 7.0** Set to `true` to confirm the feature compatibility change and allow the operation to proceed. If you omit the `confirm` parameter or set `confirm` to a value other than `true`, the command fails and returns a warning about modifying the feature compatibility version. ### writeConcern *Optional* The `writeConcern` specifies the write concern [`wtimeout`](https://www.mongodb.com/docs/manual/reference/write-concern.md#std-label-wc-wtimeout) value in milliseconds: - The time period that the [primary](https://www.mongodb.com/docs/manual/reference/glossary.md#std-term-primary) waits for acknowledgment from the majority of the replica set members. If the acknowledgment is not received in the time period, the operation fails. - Default is `60000` milliseconds. Use a longer time period if the [secondary](https://www.mongodb.com/docs/manual/reference/glossary.md#std-term-secondary) members of the replica set have a delay that exceeds the [`wtimeout`](https://www.mongodb.com/docs/manual/reference/write-concern.md#std-label-wc-wtimeout) default. **Note:** - For a standalone, run the command on the standalone [`mongod`](https://www.mongodb.com/docs/manual/reference/program/mongod.md#mongodb-binary-bin.mongod) instance. - For a replica set, run the command on the primary. A majority of the data-bearing members must be available. - For a sharded cluster, run the command on a [`mongos`](https://www.mongodb.com/docs/manual/reference/program/mongos.md#mongodb-binary-bin.mongos) instance. ### dryRun *Optional* If set to `true`, MongoDB simulates an upgrade or downgrade of the feature compatibility version. If the cluster contains incompatible data, the operation fails with an error. **New in version 8.3** ## Behavior If you must downgrade the [feature compatibility version](https://www.mongodb.com/docs/manual/reference/command/setFeatureCompatibilityVersion.md#std-label-view-fcv) below 8.0, you must first run the `transitionToDedicatedConfigServer` command. For downgrade details, see [Downgrade Feature Compatibility Version.](https://www.mongodb.com/docs/manual/core/sharded-cluster-config-servers.md#std-label-sharded-cluster-config-server-config-shards-downgrade) ### Upgrade with Forward-Incompatible Data If you try to upgrade the FCV (feature compatibility version) of a cluster that contains forwards-incompatible data in the upgraded version, you receive a `CannotUpgrade` error. Forwards-incompatible data can refer to any data in your cluster that relies on a feature that was removed in the target version. When this error occurs, either: - Modify your cluster data to remove forwards-incompatible features, then re-run the `setFeatureCompatibilityVersion` command with the upgraded version to set the FCV (feature compatibility version) to the upgraded version. - Run the `setFeatureCompatibilityVersion` command with the original downgraded version to set the FCV (feature compatibility version) back to the original version. **Important:** Setting the FCV (feature compatibility version) to the original version stops the upgrade procedure and reverts the FCV (feature compatibility version) to the downgraded version. The cluster does not return to its state before the FCV (feature compatibility version) upgrade began. If the FCV (feature compatibility version) upgrade confirms that there is no forwards-incompatible data but otherwise stops or fails, any subsequent FCV downgrade attempts also fail with an error message. You must complete the FCV upgrade before you can downgrade the FCV. ### Downgrade with Backward-Incompatible Data If you try to downgrade the FCV (feature compatibility version) of a cluster that contains backwards-incompatible data in the downgraded version, you receive a `CannotDowngrade` error. Backwards-incompatible data can refer to any data in your cluster that relies on a feature that isn't available in the target version. When this error occurs, either: - Modify your cluster data to remove backwards-incompatible features, then re-run the `setFeatureCompatibilityVersion` command with the downgraded version to set the FCV (feature compatibility version) to the downgraded version. - Run the `setFeatureCompatibilityVersion` command with the original upgraded version to set the FCV (feature compatibility version) back to the original version. **Important:** Setting the FCV (feature compatibility version) to the original version stops the downgrade procedure and reverts the FCV (feature compatibility version) to the upgraded version. The cluster does not return to its state before the FCV (feature compatibility version) downgrade began. If the FCV (feature compatibility version) downgrade confirms that there is no backwards-incompatible data but otherwise stops or fails, any subsequent FCV upgrade attempts also fail with an error message. You must complete the FCV downgrade before you can upgrade the FCV. ### Downgrade Policy in MongoDB 8.3 Starting in 8.3, you can downgrade your deployment's FCV (feature compatibility version) to the immediately previous minor version. To learn more, see [Downgrade 8.3 to 8.2.](https://www.mongodb.com/docs/manual/release-notes/8.3-downgrade.md#std-label-8.3-downgrade) ### Conflicts with Background Operations Certain background operations may prevent execution of [`setFeatureCompatibilityVersion`](https://www.mongodb.com/docs/manual/reference/command/setFeatureCompatibilityVersion.md#mongodb-dbcommand-dbcmd.setFeatureCompatibilityVersion). Use [`currentOp`](https://www.mongodb.com/docs/manual/reference/command/currentOp.md#mongodb-dbcommand-dbcmd.currentOp) to identify any ongoing operations. ### Sync Failures If you change the FCV (feature compatibility version) during an initial sync, the sync may fail with an `OplogOperationUnsupported` error when replaying entries on the `oplog` application phase. The next sync succeeds because the operation phase no longer replays the operation. ### Default Values | Deployments | `featureCompatibilityVersion` | | --- | --- | | For new 8.3 deployments | `"8.3"` | | For 8.3 deployments [upgraded from 8.2](https://www.mongodb.com/docs/manual/release-notes/8.3.md#std-label-8.3-upgrade) | `"8.2"` until you [`setFeatureCompatibilityVersion`](https://www.mongodb.com/docs/manual/reference/command/setFeatureCompatibilityVersion.md#mongodb-dbcommand-dbcmd.setFeatureCompatibilityVersion) to `"8.3"`. | | For new 8.0 deployments | `"8.0"` | | For 8.0 deployments [upgraded from 7.0](https://www.mongodb.com/docs/manual/release-notes/8.0.md#std-label-8.0-upgrade) | `"7.0"` until you [`setFeatureCompatibilityVersion`](https://www.mongodb.com/docs/manual/reference/command/setFeatureCompatibilityVersion.md#mongodb-dbcommand-dbcmd.setFeatureCompatibilityVersion) to `"8.0"`. | | For new 7.0 deployments | `"7.0"` | | For 7.0 deployments [upgraded from 6.0](https://www.mongodb.com/docs/manual/release-notes/7.0.md#std-label-7.0-upgrade) | `"6.0"` until you [`setFeatureCompatibilityVersion`](https://www.mongodb.com/docs/manual/reference/command/setFeatureCompatibilityVersion.md#mongodb-dbcommand-dbcmd.setFeatureCompatibilityVersion) to `"7.0"`. | ### Idempotency This command must perform writes to an internal system collection. If the command does not complete successfully, you can safely retry it. The operation is idempotent. ### Cluster-to-Cluster Sync and User Write Blocking Starting in MongoDB 6.0, if you need to downgrade the feature compatibility version, ensure you disable cluster-to-cluster replication and user write blocking. 1. If you enabled cluster-to-cluster replication, disable it. 2. If you enabled user write blocking, disable it: ```javascript db.runCommand( { setUserWriteBlockMode: 1, global: false } ) ``` 3. Wait for the previous command to complete. 4. Downgrade the feature compatibility version using [`setFeatureCompatibilityVersion`.](https://www.mongodb.com/docs/manual/reference/command/setFeatureCompatibilityVersion.md#mongodb-dbcommand-dbcmd.setFeatureCompatibilityVersion) For more information on MongoDB Cluster-to-Cluster Sync, see the [documentation.](https://www.mongodb.com/docs/cluster-to-cluster-sync/current) ### Feature Compatibility in Arbiters Arbiters do not replicate the [`admin.system.version`](https://www.mongodb.com/docs/manual/reference/system-collections.md#mongodb-data-admin.system.version) collection. Because of this, arbiters always have a feature compatibility version equal to the downgrade version of the binary, regardless of the FCV value of the replica set. For example, an arbiter in a MongoDB 5.0 cluster, has an FCV value of 4.4. ## Examples ### Get FeatureCompatibilityVersion To view the `featureCompatibilityVersion` for a [`mongod`](https://www.mongodb.com/docs/manual/reference/program/mongod.md#mongodb-binary-bin.mongod) instance, run the [`getParameter`](https://www.mongodb.com/docs/manual/reference/command/getParameter.md#mongodb-dbcommand-dbcmd.getParameter) command on a [`mongod`](https://www.mongodb.com/docs/manual/reference/program/mongod.md#mongodb-binary-bin.mongod) instance: ```javascript db.adminCommand( { getParameter: 1, featureCompatibilityVersion: 1 } ) ``` The output resembles: ```javascript { featureCompatibilityVersion: { version: '5.0' }, ok: 1, '$clusterTime': { clusterTime: Timestamp({ t: 1660318752, i: 5 }), signature: { hash: Binary(Buffer.from("ce0cff3621e9b089fa6d8e9a1e1efc1a1ff15dab", "hex"), 0), keyId: Long("7129893797260951557") } }, operationTime: Timestamp({ t: 1660318752, i: 5 }) } ``` **Note:** The operation is undefined on the [`mongos`](https://www.mongodb.com/docs/manual/reference/program/mongos.md#mongodb-binary-bin.mongos) instances. On a sharded cluster that has access control enabled, you must connect to the shard as a [shard local user](https://www.mongodb.com/docs/manual/core/security-users.md#std-label-shard-local-users) to run the command. ### Set Feature Compatibility Version on MongoDB 8.0 Deployments #### Enable 8.0 Backwards Incompatible Features To enable the [8.0 features that persist data incompatible with MongoDB 7.0](https://www.mongodb.com/docs/manual/release-notes/8.0-compatibility.md#std-label-8.0-downgrade-incompatible), set the feature compatibility to `"8.0"` on the MongoDB 8.0 deployment: **Note:** Run the [`setFeatureCompatibilityVersion`](https://www.mongodb.com/docs/manual/reference/command/setFeatureCompatibilityVersion.md#mongodb-dbcommand-dbcmd.setFeatureCompatibilityVersion) command against the `admin` database. - For a standalone, run the command on the standalone [`mongod`](https://www.mongodb.com/docs/manual/reference/program/mongod.md#mongodb-binary-bin.mongod) instance. - For a replica set, run the command on the primary. A majority of the data-bearing members must be available. - For a sharded cluster, run the command on a [`mongos`](https://www.mongodb.com/docs/manual/reference/program/mongos.md#mongodb-binary-bin.mongos) instance. ```javascript db.adminCommand( { setFeatureCompatibilityVersion: "8.0", confirm: true } ) ``` #### Disable 8.0 Backwards Incompatible Features To disable the [8.0 features that persist data incompatible with MongoDB 7.0](https://www.mongodb.com/docs/manual/release-notes/8.0-compatibility.md#std-label-8.0-downgrade-incompatible), set the feature compatibility to `"7.0"` on the MongoDB 8.0 deployment: **Note:** Run the [`setFeatureCompatibilityVersion`](https://www.mongodb.com/docs/manual/reference/command/setFeatureCompatibilityVersion.md#mongodb-dbcommand-dbcmd.setFeatureCompatibilityVersion) command against the `admin` database. - For a standalone, run the command on the standalone [`mongod`](https://www.mongodb.com/docs/manual/reference/program/mongod.md#mongodb-binary-bin.mongod) instance. - For a replica set, run the command on the primary. A majority of the data-bearing members must be available. - For a sharded cluster, run the command on a [`mongos`](https://www.mongodb.com/docs/manual/reference/program/mongos.md#mongodb-binary-bin.mongos) instance. * `"7.0"` featureCompatibilityVersion is supported on MongoDB 7.0 and MongoDB 8.0 deployments. ```javascript db.adminCommand( { setFeatureCompatibilityVersion: "7.0", confirm: true } ) ``` If you run this command as part of the downgrade process from MongoDB 8.0 to MongoDB 7.0, you must also remove all persisted features that are [incompatible](https://www.mongodb.com/docs/manual/release-notes/8.0-compatibility.md#std-label-8.0-downgrade-incompatible) with 7.0. See the appropriate downgrade procedures. ### Set Feature Compatibility Version on MongoDB 7.0 Deployments #### Enable 7.0 Backwards Incompatible Features To enable the [7.0 features that persist data incompatible with MongoDB 6.0](https://www.mongodb.com/docs/manual/release-notes/7.0-compatibility.md#std-label-7.0-downgrade-incompatible), set the feature compatibility to `"7.0"` on the MongoDB 7.0 deployment: **Note:** Run the [`setFeatureCompatibilityVersion`](https://www.mongodb.com/docs/manual/reference/command/setFeatureCompatibilityVersion.md#mongodb-dbcommand-dbcmd.setFeatureCompatibilityVersion) command against the `admin` database. - For a standalone, run the command on the standalone [`mongod`](https://www.mongodb.com/docs/manual/reference/program/mongod.md#mongodb-binary-bin.mongod) instance. - For a replica set, run the command on the primary. A majority of the data-bearing members must be available. - For a sharded cluster, run the command on a [`mongos`](https://www.mongodb.com/docs/manual/reference/program/mongos.md#mongodb-binary-bin.mongos) instance. ```javascript db.adminCommand( { setFeatureCompatibilityVersion: "7.0", confirm: true } ) ``` #### Disable 7.0 Backwards Incompatible Features To disable the [7.0 features that persist data incompatible with MongoDB 6.0](https://www.mongodb.com/docs/manual/release-notes/7.0-compatibility.md#std-label-7.0-downgrade-incompatible), set the feature compatibility to `"6.0"` on the MongoDB 7.0 deployment: **Note:** Run the [`setFeatureCompatibilityVersion`](https://www.mongodb.com/docs/manual/reference/command/setFeatureCompatibilityVersion.md#mongodb-dbcommand-dbcmd.setFeatureCompatibilityVersion) command against the `admin` database. - For a standalone, run the command on the standalone [`mongod`](https://www.mongodb.com/docs/manual/reference/program/mongod.md#mongodb-binary-bin.mongod) instance. - For a replica set, run the command on the primary. A majority of the data-bearing members must be available. - For a sharded cluster, run the command on a [`mongos`](https://www.mongodb.com/docs/manual/reference/program/mongos.md#mongodb-binary-bin.mongos) instance. * `"6.0"` featureCompatibilityVersion is supported on MongoDB 6.0 and MongoDB 7.0 deployments only. ```javascript db.adminCommand( { setFeatureCompatibilityVersion: "6.0", confirm: true } ) ``` If run as part of the downgrade process from MongoDB 7.0 to MongoDB 6.0, you must also remove all persisted features that are [incompatible](https://www.mongodb.com/docs/manual/release-notes/7.0-compatibility.md#std-label-7.0-downgrade-incompatible) with 6.0. See the appropriate downgrade procedures. ### Set Write Concern Timeout The following example sets the optional write concern [`wtimeout`](https://www.mongodb.com/docs/manual/reference/write-concern.md#std-label-wc-wtimeout) field to 5000 (5 seconds). **Note:** Run the [`setFeatureCompatibilityVersion`](https://www.mongodb.com/docs/manual/reference/command/setFeatureCompatibilityVersion.md#mongodb-dbcommand-dbcmd.setFeatureCompatibilityVersion) command against the `admin` database. - For a standalone, run the command on the standalone [`mongod`](https://www.mongodb.com/docs/manual/reference/program/mongod.md#mongodb-binary-bin.mongod) instance. - For a replica set, run the command on the primary. A majority of the data-bearing members must be available. - For a sharded cluster, run the command on a [`mongos`](https://www.mongodb.com/docs/manual/reference/program/mongos.md#mongodb-binary-bin.mongos) instance. ```javascript db.adminCommand( { setFeatureCompatibilityVersion: "5.0", writeConcern: { wtimeout: 5000 } } ) ``` ## Troubleshooting If you experience startup issues after setting your feature compatibility version, contact [MongoDB Support](https://support.mongodb.com/welcome) for assistance.