> For the complete MongoDB documentation index, see www.mongodb.com/docs/llms.txt # mongosync Migration Limitations **Warning:** Mongosync doesn't support MongoDB 9.0. Do not upgrade to MongoDB 9.0 if you use Mongosync. `mongosync` doesn't check for compliance with the limitations below. Running `mongosync` outside of these limitations may lead to undefined behavior on the destination cluster. You must adhere to these limitations for the full duration of the migration, including while a migration is paused or stopped if you plan to resume it. ## MongoDB Server Compatibility For supported MongoDB server versions, see [MongoDB Server Version Compatibility.](https://www.mongodb.com/docs/mongosync/current/reference/supported-server-version.md#std-label-c2c-server-version-compatibility) ### MongoDB Community Edition MongoDB does not test Mongosync with Community builds and in most cases, MongoDB does not offer support for Mongosync with Community deployments. If you would like to use Mongosync with MongoDB Community Edition, contact a MongoDB sales representative to discuss requirements and individualized options. ### Pre-6.0 Migrations Starting in mongosync 1.10, `mongosync` supports migrations from source clusters running MongoDB server versions older than 6.0. For information on supported migration paths, see [MongoDB Server Version Compatibility.](https://www.mongodb.com/docs/mongosync/current/reference/supported-server-version.md#std-label-c2c-server-version-compatibility) The following limitations apply to pre-6.0 migrations: - The source cluster cannot have [orphaned documents](https://www.mongodb.com/docs/manual/reference/glossary.md#std-term-orphaned-document). To clean up any orphaned documents, run the [`cleanupOrphaned`](https://www.mongodb.com/docs/manual/reference/command/cleanupOrphaned.md#mongodb-dbcommand-dbcmd.cleanupOrphaned) command on the `mongod` instances on every shard's primary node on their source cluster. Wait for this command to complete with a status `{ok:1}` before starting the migration. - Writes that produce [DDL](https://www.mongodb.com/docs/manual/reference/glossary.md#std-term-DDL--Data-Definition-Language-) events cannot occur on the source cluster during the migration. The following events cannot occur: - `collMod` - `create` - `createIndexes` - `drop` - `dropDatabase` - `dropIndexes` - `refineCollectionShardKey` - `rename` - `reshardCollection` - `shardCollection` This includes operations that may create new collections such as [`mapReduce`](https://www.mongodb.com/docs/manual/reference/command/mapReduce.md#mongodb-dbcommand-dbcmd.mapReduce), [`$out`](https://www.mongodb.com/docs/manual/reference/operator/aggregation/out.md#mongodb-pipeline-pipe.-out), and [`$merge`](https://www.mongodb.com/docs/manual/reference/operator/aggregation/merge.md#mongodb-pipeline-pipe.-merge). This also includes collections created implicitly from inserts. Only writes that produce CRUD events can occur during the migration. **Note:** Writes that produce DDL events on source collections outside of the [namespace filter](https://www.mongodb.com/docs/mongosync/current/reference/collection-level-filtering.md#std-label-c2c-filtered-sync) are allowed. - `geoHaystack` indexes are not supported. - [/reverse](https://www.mongodb.com/docs/mongosync/current/reference/api/reverse.md#std-label-c2c-api-reverse) endpoint is not supported. You can't enable the `reversible` option in the [/start](https://www.mongodb.com/docs/mongosync/current/reference/api/start.md#std-label-c2c-api-start) request. - Ensure that no writes are made to the source cluster after you call the `/commit` endpoint. - You can't enable the `createSupportingIndexes` [sharding parameter](https://www.mongodb.com/docs/mongosync/current/reference/api/start.md#std-label-c2c-api-start-sharding). Instead, create an index to support your shard key on the source cluster. - If there are any indexes with inconsistent specs or that are missing on one or more shards, `mongosync` returns an error. To check for index inconsistencies, see [Find Inconsistent Indexes Across Shards.](https://www.mongodb.com/docs/manual/tutorial/manage-indexes.md#std-label-manage-indexes-find-inconsistent-indexes) ## General Limitations - `mongosync` does not support in-place server version upgrades or downgrades that change the major or minor version during a migration. `mongosync` does allow patch version upgrades. To learn more, see the [server upgrade instructions.](https://www.mongodb.com/docs/manual/tutorial/upgrade-revision.md#std-label-upgrade-to-latest-revision) - `mongosync` doesn't validate that the clusters or the environment are properly configured. - Other clients must not write to the destination cluster while `mongosync` is running. - [system.\* collections](https://www.mongodb.com/docs/manual/reference/system-collections.md#std-label-metadata-system-collections) aren't replicated. - Documents that have dollar (`$`) prefixed field names aren't supported. See [Field Names with Periods and Dollar Signs.](https://www.mongodb.com/docs/manual/core/dot-dollar-considerations.md#std-label-crud-concepts-dot-dollar-considerations) - Serverless clusters aren't supported. - A MongoDB Shared Tier isn't supported. - Atlas Infinite clusters aren't supported. - [Queryable Encryption](https://www.mongodb.com/docs/v6.0/core/queryable-encryption/) isn't supported. - [Client-Side Field Level Encryption](https://www.mongodb.com/docs/manual/core/csfle/) isn't supported. - You cannot sync a collection that has a unique index and a non-unique index defined on the same field(s). - Before you attempt to run `mongosync` with an `M10+` Atlas cluster, disable the Require Indexes for All Queries option to set [`notablescan`](https://www.mongodb.com/docs/manual/reference/parameters.md#mongodb-parameter-param.notablescan) to `false` on both the source and destination clusters. - `mongosync` doesn't sync users or roles. - `mongosync` does not replicate [`applyOps`](https://www.mongodb.com/docs/manual/reference/command/applyOps.md#mongodb-dbcommand-dbcmd.applyOps) operations made on the source cluster during sync to the destination cluster. - `mongosync` must read from the source cluster using the [`primary`](https://www.mongodb.com/docs/manual/core/read-preference.md#mongodb-readmode-primary) read preference. - `mongosync` does not support source or destination clusters that are currently upgrading or downgrading MongoDB versions. - `mongosync` does not support syncing [Atlas Search Indexes.](https://www.mongodb.com/docs/atlas/atlas-search/create-index/) - `mongosync` only supports clusters that use the [WiredTiger](https://www.mongodb.com/docs/manual/core/wiredtiger.md#std-label-storage-wiredtiger) storage engine. - You can't sync a collection with any documents that have an empty timestamp, such as `Timestamp(0,0)` on pre-6.0 source clusters. - `mongosync` does not support documents with duplicate field names. For details, see [MongoDB does not support duplicate field names.](https://www.mongodb.com/docs/manual/reference/limits/#mongodb-does-not-support-duplicate-field-names) - `mongosync` does not support migrating a namespace to a destination cluster that already contains a conflicting namespace. - `mongosync` does not support destination clusters without any provisioned users. - In all MongoDB versions before 8.0.20, if a `replace` operation adds a field named `$v` to a document, `mongosync` exits with an unrecoverable fatal error during change event application. Resuming the sync always fails with the same error. To resolve this issue, restart the sync from scratch, deleting `mongosync`'s metadata database on the destination, or upgrade the source cluster to 8.0.20+. ## Unsupported Collection Types - Time-series collections aren't supported. - Clustered collections with [expireAfterSeconds](https://www.mongodb.com/docs/manual/reference/method/db.createCollection.md#std-label-db.createCollection.expireAfterSeconds) set aren't supported. ## Destination Disk Space **New in version 1.22** Before `mongosync` starts a migration, it checks the disk space available on the destination cluster. `mongosync` estimates the on-disk size of the source collections and indexes that you selected for migration, then compares that estimate to the space available on the destination filesystem. `mongosync` applies a 1.25x safety factor to the estimate to account for storage engine compression differences, temporary space that index builds use, and oplog growth during the migration. If the estimated space required exceeds the space available, `/start` returns an `InsufficientDestinationDiskSpace` error, and `mongosync` does not start the migration. To resolve the error, free disk space on the destination cluster and call `/start` again. `mongosync` skips the check for destinations where it cannot retrieve filesystem statistics. **Important:** This check is a best-effort guardrail. It does not guarantee that the migration fits on the destination cluster. Changes that occur during the migration and differences in how `mongosync` distributes disk space across destination shards both affect the estimate. To disable the check, set `skipDiskSpaceCheck` to `true` in the `/start` request. Use this option when the destination filesystem statistics do not accurately represent the storage available to the migration. To learn more, see [Request Body Parameters.](https://www.mongodb.com/docs/mongosync/current/reference/api/start.md#std-label-c2c-api-start-params) ## Sharded Clusters - `mongosync` doesn't support sync from a sharded cluster to a replica set. - `mongosync` doesn't support sync to a sharded cluster topology with one or more arbiters. - `mongosync` doesn't support sync to or from [global clusters.](https://www.mongodb.com/docs/atlas/global-clusters.md#std-label-global-clusters) - Sync from a replica set to a sharded cluster has the following limitations: - `mongosync` allows users to rename collections that the `sharding.shardingEntries` option includes during sync with some limitations. For details, see [Renaming During Sync.](https://www.mongodb.com/docs/mongosync/current/reference/api/start.md#std-label-rename-during-sync) - If you use the `sharding.createSupportingIndexes` option, the indexes are automatically created on the destination cluster during the sync. You cannot create these indexes afterwards on the source cluster. - If you want to create an index to support shard keys manually, you must create the index before `mongosync` starts or after the migration is complete and `mongosync` has stopped. - Within a collection, the `_id` field must be unique across all of the shards in the cluster. See [Sharded Clusters and Unique Indexes](https://www.mongodb.com/docs/manual/core/index-unique.md#std-label-sharded-clusters-unique-indexes) for more details. - The [`movePrimary`](https://www.mongodb.com/docs/manual/reference/command/movePrimary.md#mongodb-dbcommand-dbcmd.movePrimary) command cannot be used to reassign the primary shard while syncing. - There is no replication for zone configuration. `mongosync` replicates data, it doesn't inherit zones. - Shards cannot be added or removed while syncing. - `mongosync` only syncs indexes that exist on all shards. - If `mongosync` detects inconsistent index specifications across shards, it exits with a fatal error. When checking for inconsistencies, `mongosync` ignores the `ns` and `background` index fields. **Note:** To check for index inconsistencies, see [Find Inconsistent Indexes Across Shards](https://www.mongodb.com/docs/manual/tutorial/manage-indexes.md#std-label-manage-indexes-find-inconsistent-indexes). This method surfaces `ns` and `background` field differences, which `mongosync` ignores when checking for inconsistencies. - If the source or destination cluster is a sharded cluster and you are not running `mongosync` with [namespace filtering](https://www.mongodb.com/docs/mongosync/current/reference/collection-level-filtering.md#std-label-c2c-filtered-sync), you must disable the source cluster's balancer by running the [`balancerStop`](https://www.mongodb.com/docs/manual/reference/command/balancerStop.md#mongodb-dbcommand-dbcmd.balancerStop) command and waiting 15 minutes for the command to complete. If the source or destination cluster is a sharded cluster and you are running `mongosync` with namespace filtering, you can globally enable the source cluster's balancer but you must disable it for all collections within the namespace filter. See [Disabling Balancer for Collections in Filtered Sync](https://www.mongodb.com/docs/mongosync/current/reference/mongosync-behavior.md#std-label-disabling-balancer-filtered). You can also fully disable the source cluster's balancer. You must always disable the balancer on a sharded destination cluster by using [`balancerStop`.](https://www.mongodb.com/docs/manual/reference/command/balancerStop.md#mongodb-dbcommand-dbcmd.balancerStop) - If you have enabled the source cluster's balancer, but disabled it for collections within the namespace filter, do not run [`shardCollection`](https://www.mongodb.com/docs/manual/reference/command/shardCollection.md#mongodb-dbcommand-dbcmd.shardCollection) on collections within the namespace filter. If you run [`shardCollection`](https://www.mongodb.com/docs/manual/reference/command/shardCollection.md#mongodb-dbcommand-dbcmd.shardCollection) on collections within the namespace filter during the migration, `mongosync` returns an error and stops, which requires you to start the migration from scratch. - `mongosync` doesn't support running the command [`transitionFromDedicatedConfigServer`](https://www.mongodb.com/docs/manual/reference/command/transitionFromDedicatedConfigServer.md#mongodb-dbcommand-dbcmd.transitionFromDedicatedConfigServer) during execution. - You must not run the [`moveChunk`](https://www.mongodb.com/docs/manual/reference/command/moveChunk.md#mongodb-dbcommand-dbcmd.moveChunk) and [`moveRange`](https://www.mongodb.com/docs/manual/reference/command/moveRange.md#mongodb-dbcommand-dbcmd.moveRange) commands on the source or destination clusters. - The shard key cannot be [refined](https://www.mongodb.com/docs/manual/core/sharding-refine-a-shard-key.md#std-label-shard-key-refine) while syncing. - The [`reshardCollection`](https://www.mongodb.com/docs/manual/reference/command/reshardCollection.md#mongodb-dbcommand-dbcmd.reshardCollection) operations from the source cluster are not supported during sync. - The maximum number of indexes per sharded collection is 63, which is one less than the [default limit](https://www.mongodb.com/docs/manual/reference/limits.md#std-label-limit-number-of-indexes-per-collection) of 64. - `mongosync` does not support collections with a non-default collation on sharded clusters. This applies to both sharded and unsharded collections. - `mongosync` errors on indexes that are inconsistent or missing on some data-bearing shards. - `mongosync` fails if there is a [balancing window](https://www.mongodb.com/docs/manual/tutorial/manage-sharded-cluster-balancer.md#std-label-sharded-cluster-config-balancing-window) configured on the source or destination cluster. - `mongosync` does not support migrating into destination namespaces with pre-configured shard zone tags. Before starting a migration, remove all shard tag ranges, or zones, from any namespaces that `mongosync` will migrate into on the destination. You can re-add the desired zone ranges after the migration reaches the `COMMITTED` state. ## Reversing - If you do not call the [/commit](https://www.mongodb.com/docs/mongosync/current/reference/api/commit.md#std-label-c2c-api-commit) endpoint to finalize the reverse sync, the original source cluster remains in an unusable, intermediate state. - If the old source has [unique indexes](https://www.mongodb.com/docs/manual/core/index-unique.md#std-label-index-type-unique) which are partially distributed across shards, reversing may cause failures. Ensure that unique indexes exist on all shards before reversing. * The source and destination clusters must have the same number of shards. You cannot reverse sync when the clusters have different topologies. * The source and destination clusters must run the same MongoDB major version. - To reverse direction, `mongosync` requires that all [unique](https://www.mongodb.com/docs/manual/core/index-unique.md#std-label-index-type-unique) indexes on the source cluster (except for `_id`) do not have legacy unique index keys. ## Multiple Clusters - `mongosync` does not support syncing multiple source clusters to one destination cluster. - One cluster cannot simultaneously be a source cluster in one `mongosync` instance and a destination cluster in another `mongosync` instance. ## Filtered Sync - Filtering is not supported with [reversible sync.](https://www.mongodb.com/docs/mongosync/current/reference/api/reverse.md#std-label-c2c-api-reverse) - The destination cluster must not contain user data prior to starting unless you set the [preExistingDestinationData](https://www.mongodb.com/docs/mongosync/current/reference/api/start.md#std-label-c2c-pre-existing-dest-data) parameter to `true` when you call `/start`. - The destination cluster must not contain the `__mdb_internal_mongosync` system database prior to starting. - You cannot modify a filter that is in use. To create a new filter, see: [Replace an Existing Filter.](https://www.mongodb.com/docs/mongosync/current/reference/collection-level-filtering.md#std-label-c2c-change-filter) - You can only rename collections in certain situations. For more details see: [Adding and Renaming Collections.](https://www.mongodb.com/docs/mongosync/current/reference/collection-level-filtering.md#std-label-c2c-filter-renaming-collections) - If a filter includes a [view](https://www.mongodb.com/docs/manual/core/views.md#std-label-views-landing-page) but not the base collection, only the view metadata syncs to the destination cluster. To include the view documents, you must also sync the base collection. - You cannot specify system collections or system databases in a filter. - To use the [`$out`](https://www.mongodb.com/docs/manual/reference/operator/aggregation/out.md#mongodb-pipeline-pipe.-out) aggregation stage or the [`mapReduce`](https://www.mongodb.com/docs/manual/reference/command/mapReduce.md#mongodb-dbcommand-dbcmd.mapReduce) command (when set to create or replace a collection) with filtering, you must configure the filter to use the entire database. You cannot limit the filter to collections within the database. For more information, see [Filtering with mapReduce and $out.](https://www.mongodb.com/docs/mongosync/current/reference/collection-level-filtering.md#std-label-c2c-filter-with-out) ## Capped Collections Starting in 1.3.0, Mongosync supports [capped collections](https://www.mongodb.com/docs/manual/core/capped-collections.md#std-label-manual-capped-collection) with some limitations. Starting in 1.20.0, you must pass the [`--enableCappedCollectionHandling`](https://www.mongodb.com/docs/mongosync/current/reference/mongosync-binary.md#std-option-mongosync.--enableCappedCollectionHandling) flag when starting `mongosync` to enable creating new capped collections during a migration. - [`convertToCapped`](https://www.mongodb.com/docs/manual/reference/command/convertToCapped.md#mongodb-dbcommand-dbcmd.convertToCapped) is not supported. If you run `convertToCapped`, `mongosync` exits with an error. - [`cloneCollectionAsCapped`](https://www.mongodb.com/docs/manual/reference/command/cloneCollectionAsCapped.md#mongodb-dbcommand-dbcmd.cloneCollectionAsCapped) is not supported. Capped collections on the source cluster work normally during sync. Capped collections on the destination cluster have temporary changes during sync: - There is no maximum number of documents. - The maximum collection size is 1PB. `mongosync` restores the original values for maximum number of documents and maximum document size during commit. ## System Collections Mongosync does not replicate [system collections](https://www.mongodb.com/docs/manual/reference/system-collections.md#std-label-metadata-system-collections) to the destination cluster. If you issue a [`dropDatabase`](https://www.mongodb.com/docs/manual/reference/command/dropDatabase.md#mongodb-dbcommand-dbcmd.dropDatabase) command on the source cluster, this change is not directly applied on the destination cluster. Instead, Mongosync drops user collections and views in the database on the destination cluster, but it does not drop system collections on that database. For example, on the destination cluster: - The drop operation does not affect a user-created [`system.js`](https://www.mongodb.com/docs/manual/reference/system-collections.md#mongodb-data--database-.system.js) collection. - If you enable profiling, the [`system.profile`](https://www.mongodb.com/docs/manual/reference/system-collections.md#mongodb-data--database-.system.profile) collection remains. - If you create views on the source cluster and then drop the database, replicating the drop removes the views, but leaves an empty [`system.views`](https://www.mongodb.com/docs/manual/reference/system-collections.md#mongodb-data--database-.system.views) collection. In these cases, the replication of `dropDatabase` removes all user-created collections from the database, but leaves its system collections on the destination cluster. ## Index Builds When `buildIndexes` is set to `"afterDataCopy"`, `mongosync` might fail to apply `Rename` [DDL](https://www.mongodb.com/docs/manual/reference/glossary.md#std-term-DDL--Data-Definition-Language-) events. If this occurs, restart the migration from scratch with `buildIndexes` set to `"beforeDataCopy"` or `"never"`. Setting `buildIndexes` to `beforeDataCopy` can increase the migration time, and setting `buildIndexes` to `never` requires you to build indexes manually after the migration completes. ## Rolling Index Builds `mongosync` does not support [rolling index builds](https://www.mongodb.com/docs/manual/tutorial/build-indexes-on-replica-sets.md#std-label-index-building-replica-sets) during migration. To avoid building indexes in a rolling fashion during migration, use one of the following methods to ensure that your destination indexes match your source indexes: - Build the index on the source before migration. - Build the index on the source during migration with a [default index build.](https://www.mongodb.com/docs/manual/core/index-creation.md#std-label-index-creation-background) - Build the index on the destination after migration. ## Embedded Verifier Starting in 1.9, `mongosync` can use an embedded verifier to confirm the successful sync of collections from the source cluster to the destination cluster. ### Compatibility The embedded verifier is not available in Mongosync 1.8 and earlier. For alternative verification methods, see [Verify Data Transfer.](https://www.mongodb.com/docs/mongosync/current/reference/verification.md#std-label-c2c-verification) ### Limitations The embedded verifier has the following limitations: - `mongosync` stores the verifier state in memory, which can result in a significant memory overhead. To run the verifier, `mongosync` requires approximately 10 GB of memory, plus an additional 500 MB for every 1 million documents. - The verifier cannot be resumed. If a user stops or pauses sync and then starts `mongosync` again for any reason, the verification process restarts from the beginning. This can cause verification to fall substantially behind the migration. - When migrating from a replica set to a sharded cluster, you cannot rename source collections that you specify in the [sharding options](https://www.mongodb.com/docs/mongosync/current/reference/api/start.md#std-label-c2c-api-start-sharding). If you rename a collection included in the sharding options during the [CEA phase](https://www.mongodb.com/docs/mongosync/current/about-mongosync.md#std-label-c2c-cea), the verifier reports a sharding mismatch. - If you start sync with verification enabled and `buildIndexes` set to `never`, the migration will fail if `mongosync` finds a TTL collection on the source cluster. This can happen after you call the `/start` endpoint or much later, such as where a user creates a TTL index on the source cluster while a migration is in progress. To sync TTL collections without building indexes on the destination cluster, you must start sync with the [verifier disabled.](https://www.mongodb.com/docs/mongosync/current/reference/api/start.md#std-label-c2c-disabled-verifier) ### Unsupported Verification Checks The verifier doesn't check the following namespaces: - Capped collections - Collections with TTL indexes, including TTL indexes that are added or dropped during migration - Collections that don't use the default collation To verify unsupported collections, add additional script code to examine the collections. For more information, see [Verify Data Transfer.](https://www.mongodb.com/docs/mongosync/current/reference/verification.md#std-label-c2c-verification) **Note:** Starting in version 1.10, the verifier checks for data inconsistencies from a [DDL event](https://www.mongodb.com/docs/mongosync/current/reference/limitations.md#std-label-c2c-older-version-limitations) that occurred on the pre-6.0 source cluster during migration. This is because pre-6.0 migrations do not support DDL events. To learn more, see [Pre-6.0 Migration Limitations.](https://www.mongodb.com/docs/mongosync/current/reference/limitations.md#std-label-c2c-older-version-limitations) ## Persistent Query Settings `mongosync` doesn't migrate Persistent Query Settings (PQS), which were introduced in MongoDB 8.0. If your source cluster uses PQS, you must [migrate them manually.](https://www.mongodb.com/docs/mongosync/current/reference/c2c-migrate-pqs.md#std-label-c2c-migrate-pqs)