Error handling strategy for Realm

We are designing an error handling strategy for Realm. There are a lot of points in the documentation that one needs to subscribe to Session. Error events and respond to such errors as client reset or diverging history. However, there’s almost little information about a specific realm. Error events.

  1. What are the possible exceptions that the realm error can raise?
  2. Should we care about them at all in the app lifecycle?

here are some sources which I have found.

Sync errors

Hi @Vardan_Sargsyan92,

The link you posted about Realms.Exceptions is pointing to the legacy docs. The correct page is this.

To better understand what you’re after:

  1. are you trying to understand if there are links between Session.Error events and Realms.Exceptions?
  2. are you looking for recovery strategies for each Realms.Exceptions?
  3. are you just recommending us to create a more specific documentation page regarding Realms.Exceptions?

If your question is none of the above, could you specify better what is that you need to know?

1 Like

Hi @Andrea_Catalini

Thanks for the reply.

We are designing an offline-first application based on realm-sync. And to keep users’ data law-abiding and up to date, we should care about proper sync-error handling. Moreover, we should also take care of users’ data when they are offline thus, taking care of proper realm error handling. For instance, let’s consider two sync session errors.

  1. 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 and to not lose data, the user should perform a client reset.

This kind of exception should be handled (The user should be aware of possible data loss and do a client reset).

  1. 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 the 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 kind of exception is a developer error. It should not be handled and when the exception emits that means the developer made issues while designing the app and should review the code and fix issues.

In general, I’d like to know which exceptions should I show to users and which ones not?. Is there any strategy to prevent data loss when the synchronization somehow fails?

Now related to the questions above:

  1. As I understood correctly the session errors are related to the cloud realm synchronization. The realm errors are related to the local database and emit when managing it (read/write). Please correct me if I’m wrong.
  2. No. I’m looking for recovery strategies for those exceptions which are crucial for the user’s data and, they should be aware of that issues.
  3. Not exactly, but I would always be happy to see more specific documentation with samples.

Thank you for the detailed question. This allows me to give you a proper answer.

  1. As I understood correctly the session errors are related to the cloud realm synchronization. The realm errors are related to the local database and emit when managing it (read/write). Please correct me if I’m wrong.

You’re correct. The errors in Realms.Exceptions pertain to the local database and in almost all cases indicate a developer error. You should rarely see them in the wild and if you do, it’s best to send an automatic error report and fix the bug in the code.

Now, going to the part you’re mostly interested in: Realm Sync and the error handling of it.
The sync errors are going to be communicated via a SessionException and its subclasses.
The unrecoverable errors are ClientResetException and PermissionDeniedException - if the user encounters those, it’s typically most prudent to redirect them to a splash screen notifying them that such an error occurred, delete the offending local Realm file, then reinitialize the application. If the error persists, such as if there’s a diverging schema between the local and server database, you should instruct the user to download the latest version of the app or contact you.
On the other hand, sync errors that are not client reset or permission denied are recoverable and Realm will automatically reconnect after a retry. You may want to tell the user that sync is temporarily paused and will resume shortly. It may be prudent to automatically log such errors though and monitor their occurrence over time - if they suddenly start happening more often than before or affecting many users, you should investigate.

On the last part, “prevention of data loss” is a complicated matter. It requires a very laborious process of diffing the content of the downloaded realm with the local one. At that point what’s only on the local realm needs to be inserted in the downloaded one.
We realize that this process is complicated and error prone, so we’re working hard, as we speak, on automating this whole process. Unfortunately, we don’t have a timeline for release yet; therefore keep following our releases and announcements.

I hope I have given you all the information that you needed.


HI @Andrea_Catalini

Thank you so much for your thoughtful and thorough answer to my question. Everything is clear now.

During the investigation, I found out that there is one more exception that makes sense to handle
IncompatibleSyncedFileException - An exception thrown when attempting to open an incompatible Synchronized Realm file.
When such an exception occurs, the original file is moved to a backup location and a new file is
created instead. If the user wishes to migrate any data from the backup location, he/she can use the backup
config to copy the original data to the new realm.
Hope this discussion would be helpful for others. Thank you

1 Like

This topic was automatically closed 5 days after the last reply. New replies are no longer allowed.