Handle Sync Errors - Flutter SDK

Client Reset Modes

To manage the client reset process, you can specify a client reset mode in your FlexibleSyncConfiguration.clientResetHandler property when configuring a realm. You can use the following client reset modes:

• Recover or discard unsynced changes mode (default): In this client reset mode, the client reset handler first attempts to recover unsynced changes. If recovery fails, this handler falls back to the discard unsyced changes mode, which deletes all unsynced local changes. If discard unsyced changes mode fails, the handler falls back to manual recovery mode.

• Recover unsynced changes mode: In this client reset mode, the client reset handler first attempts to recover unsynced changes. If recovery fails, this handler falls back to manual recovery mode.

• Discard unsynced changes mode: This client reset mode permanently deletes all local unsynced changes made since the last successful sync. If recovery fails, this handler falls back to manual recovery mode.

• Manual recovery mode: This client reset mode provides a way for you to implement your own recovery strategy.

The following sections describe how to use these client reset modes.

Automatic vs. Manual Client Reset

The Realm SDKs provide client reset modes that automatically handle most client reset errors.

Automatic client reset modes restore your local realm file to a syncable state without closing the realm or missing notifications. The following client reset modes support automatic client resets:

• Recover unsynced changes mode

• Recover or discard unsynced changes mode

• Discard unsynced changes mode

The differences between these modes are based on how they handle changes on the device that have not yet synced to the backend. Only manual recovery mode does not perform an automatic client reset.

Choose recover unsynced changes mode to handle most client reset scenarios automatically. This attempts to recover unsynced changes when a client reset occurs.

If your app requires specific client reset logic that can't be handled automatically, you may want or need to add a manual client reset handler to the automatic client reset mode.

Client Reset with Recovery

Client Recovery is a feature that is enabled by default when you configure Device Sync. When Client Recovery is enabled, Realm automatically manages the client reset process in most cases. When you make schema changes the client can recover unsynced changes when there are no schema changes, or non-breaking schema changes.

To use Client Recovery, configure your realm with recover unsynced changes or recover or discard unsynced changes client reset modes.

When Client Recovery is enabled, these rules determine how objects are integrated, including how conflicts are resolved when both the backend and the client make changes to the same object:

• Objects created locally that were not synced before client reset are synced.

• If an object is deleted on the server, but is modified on the recovering client, the delete takes precedence and the client discards the update.

• If an object is deleted on the recovering client, but not the server, then the client applies the server's delete instruction.

• In the case of conflicting updates to the same field, the client update is applied.

For more information about configuring Client Recovery, refer to Client Recovery in the App Services documentation.

Client Recovery cannot occur when your app makes breaking schema changes. A breaking change is a change that you can make in your server-side schema that requires additional action to handle. In this scenario, client reset with fall back to a manual error client reset fallback.

For information on breaking vs. non-breaking schema changes, refer to Breaking vs. Non-Breaking Change Quick Reference in the App Services documentation.

final config = Configuration.flexibleSync(currentUser, schema,
    clientResetHandler: RecoverOrDiscardUnsyncedChangesHandler(
      // All the following callbacks are optional
      onBeforeReset: (beforeResetRealm) {
        // Executed before the client reset begins.
        // Can be used to notify the user that a reset is going
        // to happen.
      },
      onAfterRecovery: (beforeResetRealm, afterResetRealm) {
        // Executed if and only if the automatic recovery has succeeded.
      },
      onAfterDiscard: (beforeResetRealm, afterResetRealm) {
        // Executed if the automatic recovery has failed
        // but the discard unsynced changes fallback has completed
        // successfully.
      },
      onManualResetFallback: (clientResetError) {
        // Automatic reset failed. Handle the reset manually here.
        // Refer to the "Manual Client Reset Fallback" documentation
        // for more information on what you can include here.
      },
    ));

final config = Configuration.flexibleSync(currentUser, schema,
    clientResetHandler: RecoverUnsyncedChangesHandler(
      // All the following callbacks are optional
      onBeforeReset: (beforeResetRealm) {
        // Executed before the client reset begins.
        // Can be used to notify the user that a reset is going
        // to happen.
      },
      onAfterReset: (beforeResetRealm, afterResetRealm) {
        // Executed after the client reset is complete.
        // Can be used to notify the user that the reset is done.
      },
      onManualResetFallback: (clientResetError) {
        // Automatic reset failed. Handle the reset manually here.
        // Refer to the "Manual Client Reset Fallback" documentation
        // for more information on what you can include here.
      },
    ));

Discard Unsynced Changes Mode

Discard unsyced changes mode permanently deletes all local unsynced changes made since the last successful sync. If you choose to use this client reset mode, the SDK restores your local realm file to a syncable state without closing the realm and while keeping notifications fully working. If this process fails, it falls back to manual recovery mode.

Do not use recover or discard unsynced changes mode if your application cannot lose local data that has not yet synced to the backend.

To use discard unsynced changes mode, pass a DiscardUnsyncedChangesHandler callback to the Configure.clientResetHandler. This handler provides the following callback methods:

• onBeforeReset, which the SDK invokes prior to the client reset. You can use this callback to notify the user before the reset begins.

• onAfterReset, which the SDK invokes if and only if the reset completes successfully. You can use it to notify the user when the reset is complete.

• onManualResetFallback, which the SDK invokes only if the automatic recovery and the discard strategy have failed. You implement this callback to handle the reset failure, as explained in the Manual Recovery section.

The following example shows using DiscardUnsyncedChangesHandler and each of its callbacks:

final config = Configuration.flexibleSync(currentUser, schema,
    clientResetHandler: DiscardUnsyncedChangesHandler(
      onBeforeReset: (beforeResetRealm) {
        // Executed before the client reset begins.
        // Can be used to notify the user that a reset is going
        // to happen.
      },
      onAfterReset: (beforeResetRealm, afterResetRealm) {
        // Executed after the client reset is complete.
        // Can be used to notify the user that the reset is done.
      },
      onManualResetFallback: (clientResetError) {
        // Automatic reset failed. Handle the reset manually here.
        // Refer to the "Manual Client Reset Fallback" documentation
        // for more information on what you can include here.
      },
    ));

Manual Recovery Fallback

If the client reset with recovery cannot complete automatically, like when there are breaking schema changes, the client reset process falls through to a manual error handler. This may occur in any of the automatic client reset modes:

• Recover unsynced changes mode

• Recover or discard unsynced changes mode

• Discard unsyced changes mode

You must provide a manual client reset implementation in the onManualResetFallback callback of the client reset handler for these modes.

In onManualResetFallback, initiate a client reset using the ClientResetError.resetRealm() method of the ClientResetError parameter of the callback. ClientResetError.resetRealm() performs a client reset by deleting the realm on device and downloading relevant data from the server. Before you use this method, you must close all instances of the realm that you are resetting.

The following example demonstrates how you can manually handle an error case by discarding all unsynced changes:

// Lazily initialize `realm` so that it can be used in the callback
// before the realm has been opened.
late Realm realm;
final config = Configuration.flexibleSync(currentUser, schema,
    // This example uses the `RecoverOrDiscardUnsyncedChangesHandler`,
    // but the same logic could also be used with the `RecoverUnsyncedChangesHandler`
    // or the `DiscardUnsyncedChangesHandler`.
    clientResetHandler: RecoverOrDiscardUnsyncedChangesHandler(
  onManualResetFallback: (clientResetError) {
    // Prompt user to perform a client reset immediately. If they don't,
    // 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 = showUserAConfirmationDialog();
    if (didUserConfirmReset) {
      // You must close the Realm before attempting the client reset.
      realm.close();
      // Attempt the client reset.
      try {
        clientResetError.resetRealm();
        // Navigate the user back to the main page or reopen the
        // the Realm and reinitialize the current page.
      } catch (err) {
        // Reset failed.
        // Notify user that they'll need to update the app
      }
    }
  },
));

Manual Recovery Mode

Use manual recovery mode for the infrequent cases where you need to customize your data recovery process. In most cases, you should use one of the other strategies for client resets. You might want to use a manual client reset handler if the Automatic Recovery logic does not work for your app and you can't discard unsynced local data.

To use manual recovery mode, pass a ManualRecoveryHandler callback to the Configure.clientResetHandler.

The handler provides the onManualReset callback, in which you can perform the client reset. In onManualReset, initiate a client reset using the ClientResetError.resetRealm() method of the ClientResetError parameter of the callback. ClientResetError.resetRealm() performs a client reset by deleting the realm on device and downloading relevant data from the server. Before you use this method, you must close all instances of the realm that you are resetting.

// Lazily initialize `realm` so that it can be used in the callback
// before the realm has been opened.
late Realm realm;
final config = Configuration.flexibleSync(currentUser, schema,
    clientResetHandler: ManualRecoveryHandler((clientResetError) {
  // You must close the Realm before attempting the client reset.
  realm.close();
  // Handle manual client reset here...
  // Then perform the client reset.
  clientResetError.resetRealm();
}));

Test Client Reset Handling

You can manually test your application's client reset handling by terminating and re-enabling Device Sync.

When you terminate and re-enable Sync, clients that have previously connected with Sync are unable to connect until after they perform a client reset. Terminating Sync deletes the metadata from the server that allows the client to synchronize. The client must download a new copy of the realm from the server. The server sends a client reset error to these clients. So, when you terminate Sync, you trigger the client reset condition.

To test client reset handling:

1. Write data from a client application and wait for it to synchronize.

2. Terminate and re-enable Device Sync.

3. Run the client app again. The app should get a client reset error when it tries to connect to the server.