Skip to content
Percona Software for MongoDB Documentation

Rate this page
☆ ☆ ☆ ☆ ☆
Thanks for your feedback
Thank you! The feedback has been submitted.

For help, click the link below to get free database assistance or contact our experts for personalized support.

Get help from Percona

Known issues and limitations

This page lists known limitations for using Percona ClusterSync for MongoDB (PCSM).

Versions and topology

  • MongoDB versions that reached End-of-Life are not supported
  • PCSM connects only to the primary node in the replica set. You cannot force connection to secondary members using the directConnection option. This option is ignored.

Cross-version replication

  • Feature Compatibility Version (FCV) is not automatically checked between your source and target clusters

    PCSM does not automatically check the Feature Compatibility Version (FCV) between your source and target clusters. Because an incompatible FCV might cause replication failures, it is important to perform this check manually before you begin:

    Confirm the FCV for both your source and target clusters. Ensure the target cluster’s FCV is equal to or higher than the source cluster’s FCV.

  • Downgrade replication is not supported

    PCSM blocks startup if the source major version is higher than the target major version.

Sharded clusters

The following limitations apply specifically to sharded cluster replication:

  • When both the source and target are sharded clusters, PCSM does not continuously replicate sharding metadata. For ranged shard keys, PCSM uses the source chunk boundaries to initialize the target during the initial sync. Subsequent chunk migrations, splits, and merges aren’t reproduced on the target.
  • The primary shard assignment is not preserved. The target cluster can use a different primary shard.
  • Zone configuration is not replicated. See Zones for sharded data .
  • Don’t reshard a collection during an active synchronization.   Running reshardCollection, unshardCollection, or refineCollectionShardKey on a collection included in an active synchronization puts PCSM into a failure state. Complete or stop the synchronization first.
  • Replica set to sharded cluster migrations do not apply a shard key. PCSM can copy data from a replica set source to a sharded cluster target, but the migrated collections remain unsharded. If you need sharded collections on the target, apply the required shard key separately.

Data types

  • Queryable encryption is not supported
  • Users and roles are not synchronized
  • Timeseries collections are not supported
  • system.* collections are not replicated
  • Clustered collections with indexes that have the expireAfterSeconds field defined are not supported because the change stream does not provide a Time-to-Live (TTL) value for the index
  • Capped collections created or converted as the result of cloneCollectionAsCapped and convertToCapped commands are not supported. These operations don’t change the event and are not captured by the change streams.
  • Percona Memory Engine is not supported
  • Persistent Query Settings (added in MongoDB 8) are not supported
  • Documents that have field names with periods and dollar signs are not supported

MongoDB Atlas

Atlas M0 and Flex clusters do not support the appendOplogNote command. Therefore, Atlas M0 and Flex clusters are not supported as PCSM sources.

PCSM uses appendOplogNote on the source cluster to:

  • establish a safe timestamp before the initial data clone
  • advance the source change-stream frontier when the source is idle

To use any of these Atlas clusters as a PCSM source, upgrade the cluster to a dedicated tier, such as M10 or higher. See the MongoDB Atlas documentation for modifying a cluster for current upgrade procedures and limitations.

Other

The following limitations apply:

  • You cannot resume the clone phase after it fails. Resolve the issue and start a new synchronization run from the beginning.
  • Arbitrary database upgrades during a sync are not supported. For supported staged upgrades from lower to higher MongoDB major versions, follow the cross-version replication procedure.
  • Reverse synchronization, from the target cluster back to the source, is not supported.
  • External authentication through Kerberos, LDAP, and AWS IAM is not supported.
Last update: September 29, 2026
Created: September 29, 2026