Docs Menu

Sync Errors

On this page

  • Overview
  • Sync Protocol Errors
  • MongoDB Translator Errors
  • Sync Client Errors
  • Handle and Log Sync Errors

While you develop applications using Realm Sync, you may run into errors. This section lists common errors and describes how to and handle them.

Note

If you encounter an error not listed on this page, you can file a support ticket.

The following table describes Sync protocol errors and how to handle them. MongoDB Realm reports errors in your Sync logs.

Error Name
Description
ErrorBadClientFileIdent

This error occurs when the client is using a realm file that the server cannot access after terminating and re-enabling Sync.

To recover from this error, perform a client reset.

ErrorClientFileUserMismatch

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.

ErrorDivergingHistories

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.

ErrorIllegalRealmPath

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.

ErrorPermissionDenied

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.

ErrorOtherError
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.

The following errors may occur in the translation process between Sync and MongoDB Atlas.

Error Name
Description
MongoEncodingError

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.

TranslatorCorrectiveErasure
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 ObjectId or UUID as the primary key value. Alternatively, ensure that every synced object has a unique primary key, even across partitions.

The sync protocol returns an ERROR message when an error appears to have been caused by a connected client. Each message contains a code number and a description of the error.

To see the full list of sync errors, refer to the error code list in the Realm Core GitHub repository.

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:

Give Feedback
MongoDB logo
© 2021 MongoDB, Inc.

About

  • Careers
  • Legal Notices
  • Privacy Notices
  • Security Information
  • Trust Center
© 2021 MongoDB, Inc.