Docs Menu

Sync Errors

On this page

  • Overview
  • Sync Protocol Errors
  • Partition-Based Sync Errors
  • Flexible Sync Errors
  • MongoDB Translator Errors
  • Sync Client Errors
  • Handle Sync Errors
  • Set the Client Log Level

While you develop applications using Atlas Device 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 Device Sync protocol errors and how to handle them. Atlas App Services reports errors in your Device 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 Device 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 Device 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 Device 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 Device 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 when your 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 Device Sync configuration.

The following errors may occur when your 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 Places object type with the query name = "NY". If the client then tries to insert a Places object with a field name: "CT", the write triggers an ErrorWriteNotAllowed because the object is not within the subscription query.

This error triggers a client reset. To recover from this error, perform a client reset.

The following errors may occur in the translation process between Device 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 Device 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:

  • Sync is paused for so long that entries fall off the oplog.
  • You drop a collection that the translator was using.
  • The MongoDB cluster is unreachable for too long.

Because the free tier has a shared oplog, it is more vulnerable to this error.

To resolve this error, terminate and re-enable Sync.

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 Database Core GitHub repository.

Every application that uses Sync needs a sync error handler. To learn more about sync error handling, see your preferred SDK:

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.

Important

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.

←  Client ResetsAdd Sync to a Local-Only App →
Give Feedback
© 2022 MongoDB, Inc.

About

  • Careers
  • Investor Relations
  • Legal Notices
  • Privacy Notices
  • Security Information
  • Trust Center
© 2022 MongoDB, Inc.