Navigation

Client Resets

On this page

Overview

When using Realm Sync, it is possible that your client app will need to handle a client reset. While not common, it can be caused when Sync was terminated on the server. For example, a developer deploys a change that includes a destructive schema change. To fix this, they must stop Sync, modify the schema, and then re-enable Sync. This process causes the server to send a client reset message to the clients. By default, the SDK handles client reset messages automatically, but only on app startup. Until then, users will not receive any data from the server, and any changes they make will be lost during the reset. Therefore, you should handle client resets in your code to ensure users get up-to-date data.

Warning

A client reset erases all local data and downloads a new copy of the data stored in MongoDB Atlas. Performing a client reset loses all local changes made since the client last successfully synced.

Example

When a reset is required, realm sends a ClientResetException. You can add a listener on the Session.Error event and handle the client reset by calling the InitiateClientReset() method. The following example demonstrates this:

Session.Error += (sender, err) =>
{
    if (err.Exception is ClientResetException clientResetEx)
    {
        var session = (Session)sender;
        Console.WriteLine("Client Reset requested for " +
            session.Path +"due to "+ clientResetEx.Message);

        // Prompt user to perform client reset immediately. If they don't do it,
        // they won't receive any data from the server until they restart the app
        // and all changes they make will be discarded when the app restarts.
        var didUserConfirmReset = true;
        if (didUserConfirmReset)
        {
            // Close the Realm before doing the reset as it'll need
            // to be deleted and all objects obtained from it will be
            // invalidated.
            realm.Dispose();
            var didReset = clientResetEx.InitiateClientReset();
            if (didReset)
            {
                // Navigate the user back to the main page or reopen the
                // the Realm and reinitialize the current page.
            }
            else
            {
                // Reset failed - notify user that they'll need to restart the app.
            }
        }
    }
};
←   Migrations Writes  →