Sync Errors
On this page
Overview
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
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. This error triggers a client reset. 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. This error triggers a client reset. To recover from this error, perform a client reset. |
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. |
Partition-Based Sync Errors
The following errors may occur when your Realm app uses Partition-Based Sync.
Error Name | Description |
|---|---|
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. |
Flexible Sync Errors
The following errors may occur when your Realm app uses Flexible Sync.
Error Name | Description |
|---|---|
ErrorBadQuery | This error indicates the client query is invalid or malformed. This error includes a message that provides details about why the query is invalid. To recover from this error, you may need to verify the query syntax is correct, and that you are using query operators that are supported on the server. Additionally, confirm you are querying a queryable field in your Flexible Sync configuration. |
ErrorServerPermissionsChanged | This error indicates that server permissions for the file ident have changed since the last time it was used. This error triggers a client reset. To recover from this error, perform a client reset. |
ErrorInitialSyncNotCompleted | This error indicates that the client tried to open a session before the initial sync was complete. This may occur when the app has just enabled Sync, and is still in the process of building the Sync history. The client attempts to reconnect until this process is complete. Then, this error resolves and Sync begins working normally. |
ErrorWriteNotAllowed | This error occurs when a client attempts a write that is disallowed by permissions, or if the write modifies an object outside of the subscription query. Consider an example where the client application opens a subscription
on a This error triggers a client reset. To recover from this error, perform a client reset. |
MongoDB Translator Errors
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 Unsynced Documents. |
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. |
TranslatorFatalError - ChangeStreamHistoryLost | This error occurs when old entries in the oplog have expired before the server-side "translator" process could read them. Without these entries, the translator cannot bring the MongoDB cluster and the Realm object server to an equivalent state. This can happen when:
Because the free tier has a shared oplog, it is more vulnerable to this error. To resolve this error, terminate and re-enable Sync. |
Sync Client Errors
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.
Handle Sync Errors
Every application that uses Sync needs a sync error handler. To learn more about sync error handling, see your preferred SDK:
Set the Client Log Level
You can specify the client log level. Setting the log level to trace or
debug can help diagnose issues while your application is is in development.
You can log general information or details about all sync events, or log
only warnings or errors.
Verbose logging negatively impacts performance. For production deployment, reduce the log level.
For more information about available log levels, including how to set the client log level, see your preferred SDK.