Docs Menu

Docs HomeRealm

Reset a Client Realm - Java SDK

On this page

  • Discard Unsynced Changes
  • Discard Unsynced Changes after Breaking Schema Changes
  • Manually Recover Unsynced Changes


See also: Learn More About Client Resets

To learn about the causes of and strategies for handling client resets, check out the Sync Client Resets page.

The SDK reads and writes to a realm file on the device. When you use Atlas Device Sync, this local realm syncs with the application backend. Some conditions can cause the realm to be unable to sync with the backend. When this occurs, you get a client reset error.

This error means you must reset the realm file in the client application. Clients in this state may continue to run and save data locally. Until you perform the client reset, the realm does not sync with the backend.

Choose a client reset strategy to handle client reset errors. These strategies restore realm to a syncable state, but have tradeoffs:

Both options let you write custom logic to recover local changes. Neither option can recover local changes for you.

Discard unsynced changes is a less complex alternative to manual recovery. However, this strategy cannot handle every client reset error. You must maintain a manual client reset handler as a fallback.

New in version 10.10.0.

Discard unsynced changes is a client reset strategy provided by the SDK. This strategy requires minimal code. This strategy performs a reset without closing the realm or missing notifications.

It does delete all local changes made since the last successful sync. This includes any data already written to the realm but not yet synced to the application backend. Do not use this strategy if your application cannot lose unsynced data.

Discard unsynced changes cannot handle breaking or destructive schema changes. When breaking changes occur, the SDK falls back to manual recovery mode.

To use this strategy, pass an instance of DiscardUnsyncedChangesStrategy to the defaultSyncClientResetStrategy() builder method when you instantiate your App. Your DiscardUnsyncedChangesStrategy instance must implement the following methods:

  • onBeforeReset(). The SDK calls this block when it receives a client reset error from the backend. This occurs before the SDK executes the client reset strategy.

  • onAfterReset(). The SDK calls this block after successfully executing this strategy. This block provides a frozen copy of the original realm. It also returns a live instance of the realm in a syncable state.

  • onError(). The SDK calls this method during a breaking schema change. Behaves similarly to defaultClientResetStrategy().

The following example implements this strategy:


Breaking Schema Changes Require an App Schema Update

After a breaking schema change:

  • All clients must perform a client reset.

  • You must update client models affected by the breaking schema change.

The discard unsynced changes strategy cannot handle breaking changes. You must manually handle the client reset in the onError() method. This example manually discards unsynced changes to handle the client reset:


Manual recovery replaces the deprecated SyncSession.ClientResetHandler. Clients using the deprecated handler can update to manual recovery with no logic changes.

We do not recommend manual client reset recovery. It requires:

  • Substantial amounts of code

  • Schema concessions

  • Complex conflict resolution logic.

To learn more, see the Advanced Guide to Manual Client Reset Data Recovery.

←  Flexible Sync - Java SDKCall a Function - Java SDK →
Share Feedback
© 2022 MongoDB, Inc.


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