On this page
While you develop applications using Realm Sync, you may run into errors. This section lists common errors and describes how to and handle them.
If you encounter an error not listed on this page, you can file a support ticket.
Sync Protocol Errors¶
This error indicates that the client attempted to synchronize a realm file associated with an identity other than the specified user. This may occur if Sync is terminated and reenabled while the user is offline, which invalidates their previous identity.
To recover from this error, delete the local realm file and then re-open the realm.
This error indicates that the client attempted to synchronize a realm file that has a different sync history than the server realm. This may occur if Sync is terminated and reenabled while the user is offline, which invalidates their previous sync history.
To recover from this error, perform a client reset.
This error indicates that the client attempted to open a realm with a partition value of the wrong type. For example, you might see the error message "attempted to bind on illegal realm partition: expected partition to have type objectId but found string".
To recover from this error, ensure that the type of the partition value used to open the realm matches the partition key type in your Sync configuration.
This error occurs when a user's data access permissions are not sufficient for a given request. This can occur if a user attempts to open a realm without read permission or modify data without write permission.
To troubleshoot this error, review your Sync rules to make sure that users have proper data access permissions.
This error indicates an internal failure that is not covered by a more specific error. For example, this might occur when you hit the storage limit of a free tier Atlas cluster.
MongoDB Translator Errors¶
The following errors may occur in the translation process between Sync and MongoDB Atlas.
This error occurs when a MongoDB Atlas write (i.e. not a Sync client) modifies a document such that it no longer conforms to the app's schema. Documents that do not match the schema cannot be synced and any local updates to the object represented by such a document will not propagate.
For more information, see Realm Sync Schema Data Consistency.
This error occurs when a synced MongoDB cluster rejects the write operation for a propagated Sync change. This is usually caused by a duplicate key exception, which means that two objects use the same primary key. To avoid this error, use an
Sync Client Errors¶
To see the full list of sync errors, refer to the error code list in the Realm Core GitHub repository.
Handle and Log Sync Errors¶
You can configure the Realm SDKs to handle errors and generate error logs based on their severity level. To learn how, check out the following examples:
When using Realm Sync, a client reset is a serious error recovery task that your client app must perform in the following situation:
- The given synced realm on the server was restored from a backup. For example, due to a Realm server crash.
- The client app made changes to that realm since the backup was made, but did not sync those changes back to the server before the server was restored.
In other words, the client app must carry out a client reset on a given synced realm if the server is restored to a version older than the version on the client.
A client reset erases all local data and downloads a new copy of the data stored in MongoDB Atlas. Performing a client reset loses all local changes made since the client last successfully synced.