How can I test my apps error handling?


I am in the final stage before deploying the object server to the users of my app. Before I do, I want to make sure that I handle SyncServer errors correctly. What steps to I need to take to make sure that my apps handle errors correctly?

For example, how can I get the object server into a state where it will cause clients to get errors, like the Client Reset Errors? I do not understand how to trigger this error or any other errors.


To add to this. The documentation is not very clear on how to handle backups and restore. When restoring the server, it does say to stop the server, copy the data from the backup and then start again. But it doesn’t say anything about that you need to modify the permissions of the copied files in order to get the server to start again. You don’t even get error messages when you get it wrong.

Also, on Android, executing a client reset is pretty hard. The documentation says that I need to close all instances of realm before executing a client reset. How am I supposed to do this in a reliable way? I have followed the recommendations to open the realm in OnCreate, close in OnDestroy for activities and I use onStart/onStop for fragments. I kill all the activities before attempting to reset, but there is still a reference somewhere that I didn’t close and that causes the app to crash and when I don’t get a second chance when starting the app again. The user data is lost.

I think an example on how to successfully execute a client reset on Android would be super helpful! Also, if it would be possible in any way to find out what is holding on to Realm references that would also help alot. Right now, backups are pretty tricky to get right.



Client reset errors can be triggered manually by these steps.

  1. Synchronize data from your client to some server URL.
  2. Stop the server.
  3. Remove the root_dir, or at least the Realm corresponding to that URL.
  4. Start the server with a new root_dir.
  5. When the client connects again, it will get a client reset error. The reason is that the server
    file is not compatible with the client file, and the only way forward is to reset the client file.

Best regards,




The server process must have full permissions in its own root directory.

We should be clear about that in the documentation.

Don’t you get error messages in the log file or on the console when you
start the server without permissions to its root_dir?

I see error messages when that happens.
How do you start it? Did you check the log file?

I will forward your wish about an example of client reset in Android.

Best regards,



I wasn’t even able to access the Realm Console to see the logs. I found out about the permissions by manually inspecting and comparing the directories before and after copying the folders from my backup. I think the root dir had the correct permissions, but the restored data did not.

Checking Realm Status said that the server was started, however the dashboard didn’t show up and I wasn’t able to sync. I got it to work now and I am able to trigger a reset.

However, getting it to work on Android is super tricky to say the least. I still haven’t been able to get it to work on the client. Client error handling is the only thing stopping me from publishing the object server solution to my customers.


More on the Android error handling. What am I supposed to do with the file file returned from clientResetError.getBackupFile() ? It does have data that has not been synced, so I would like to add the missing data back to the synced realm. However, I don’t see how I can open the backup realm. I can’t open it using the sync configuration since that was what triggered the clientreseterrors in the firstplace and when I try to open it using a local configuration I get an Incompatible Histories error. How can I add the data back from the local file and to the synced realm? Am I missing something?


To add even further to this. Even when following the Realm documentation. Making sure that all realm instances are closed is not a trivial task. The documentation shows an example of opening the realm in a fragment when the in onCreateView and then closing it in onDestroyView. However, onDestroyView is not guaranteed to be called! And in my case it is in fact not called when I finish its parent activity.

How can I ensure all realm references are closed? If I don’t do this properly, the app crashes when I do a client reset and user data is lost.


It would be nice if there was a complete end to end implementation of

Maybe there is, but i’m having trouble finding it.


Both of those methods sound extremely important, but i’m not sure how about going about it. This section scares me because it sounds like there is a very real potential that i brick my clients.


A lot has happened with realm since this post, and a lot of the issues I faced on Android was caused by issues that have been resolved by the realm team. But I do agree, a little more guidance would be nice. In the Android docs, client resets aren’t even mentioned anymore!


FIY I finally got the ClientResets to work on Android. However, it did require an ugly hack involving thread sleeps to be able to close all realm instances. It is extremely tricky to close all realm instances in android as the lifecycle callbacks in Android activities are not always called when you expect them to.

Handling client resets on Android is error prone very unforgiving (lost data) if you fail. I have expressed my concerns about this here


@Sipe Sorry this is such a pain - we have added Stable IDs at the Core level and are in the process of exposing them to Sync. Once this is done we can almost completely mitigate client resets entirely and abstract this away from the developer so that it is a non-issue. Stay tuned.


That is awesome news! Thank you :slight_smile:


@ianward any updates? And are there any guidelines on how to correctly handle client resets on Android? Or should I just let the client crash and redownload the data from the server?


@Sipe Automatic Client Reset is actively being worked on right now. I would expect another few weeks of work