Datastore sync timing issue on poor network connection

[JncHrmn]

Description

Hi there,

We need guidance on how to reliably coordinate Amplify DataStore synchronization with our app’s navigation flow. We’ve observed two problematic scenarios:

1. App cold start (user already signed in):

• On launch, we show the native splash screen until the DataStore emits its ready event, then navigate to the Home screen and immediately run our DataStore queries.

• Occasionally, despite receiving ready, our initial queries return empty lists. Manually pulling to refresh then populates the data, suggesting we’re querying too early.

Our current approach for the cold start:

bool _userWasSignedInAtLaunch = false;

void main() async {
  WidgetsBinding widgetsBinding = WidgetsFlutterBinding.ensureInitialized();
  FlutterNativeSplash.preserve(widgetsBinding: widgetsBinding);

  await _configureAmplify();

  final session = await Amplify.Auth.fetchAuthSession(
    options: const FetchAuthSessionOptions(forceRefresh: false),
  );
  _userWasSignedInAtLaunch = session.isSignedIn;

  if (!_userWasSignedInAtLaunch) {
    FlutterNativeSplash.remove();
  }

  runApp(
    MyApp(),
  );
}

Future<void> _configureAmplify() async {
  try {
    final auth = AmplifyAuthCognito();
    final datastorePlugin =
        AmplifyDataStore(modelProvider: ModelProvider.instance);
    final api = AmplifyAPI(
      options: APIPluginOptions(modelProvider: ModelProvider.instance),
    );
    final storage = AmplifyStorageS3();
    if (Amplify.isConfigured == false) {
      await Amplify.addPlugins([datastorePlugin, auth, api, storage]);
    }
    await Amplify.configure(amplifyconfig);

    Amplify.Hub.listen(HubChannel.DataStore, (hubEvent) {
      if (hubEvent.eventName == 'ready') {
        if (_userWasSignedInAtLaunch) {
          FlutterNativeSplash.remove();
        }
      }
    });

    Amplify.Hub.listen(HubChannel.Auth, (hubEvent) async {
      switch (hubEvent.type) {
        case AuthHubEventType.signedIn:
          safePrint('User is signed in.');
          goRouter.go('/splash');

          break;
        case AuthHubEventType.signedOut:
          safePrint('User is signed out.');
          break;
        case AuthHubEventType.sessionExpired:
          safePrint('The session has expired.');
          break;
        case AuthHubEventType.userDeleted:
          safePrint('The user has been deleted.');
          break;
      }
    });
    safePrint("Amplify has been configured successfully.");
  } on Exception catch (e) {
    safePrint('An error occurred configuring Amplify: $e');
  }
}

2. Login flow (user signed out → signed in) on unreliable networks:

• Immediately after a successful sign-in, we route to a loading screen and kick off a full DataStore sync. We deliberately keep the user stuck on that screen until sync completes, because we don’t want to show an empty Home.

• Problem: On a poor connection, the sync can stall indefinitely, trapping the user on the loading screen. The only workaround currently is to restart the app—since they’re still authenticated, the app jumps straight to Home, but then shows a completely empty UI even though data exists in the cloud.

• This exposes that our “wait-for-ready” approach isn’t robust: neither retrying nor back-off logic is in place, and no fallback path exists to recover when sync never finishes.

Listen to the signedIn Event

 Amplify.Hub.listen(HubChannel.Auth, (hubEvent) async {
      switch (hubEvent.type) {
        case AuthHubEventType.signedIn:
          safePrint('User is signed in.');
          goRouter.go('/loadingScreen');

          break;

Within the loading widget/screen the trigger the following:

class DataStoreSyncService {
  Future<void> syncAfterSignIn() async {
    final completer = Completer<void>();

    final sub = Amplify.Hub.listen(HubChannel.DataStore, (hubEvent) {
      if ((hubEvent.eventName == 'ready') && !completer.isCompleted) {
        completer.complete();
      }
    });

    await Amplify.DataStore.clear();
    await Amplify.DataStore.start();

    await completer.future;
    await sub.cancel();
  }
}

What’s the recommended way to detect and wait for a truly complete initial sync, beyond listening for the ready event?
How can we implement retry/back-off or timeout logic so that users aren’t stranded on a loading screen forever?
Can we leverage additional Hub events (e.g. network status changes) or DataStore APIs (like observeQuery().isSynced) to build a more resilient loading flow and fallback UI?

We’ve tried following the Amplify docs examples, but still run into this race condition on slow networks. Any pointers, sample patterns, or code snippets would be greatly appreciated. Thanks!

Categories

• Analytics
• API (REST)
• API (GraphQL)
• Auth
• Authenticator
• DataStore
• Notifications (Push)
• Storage

Steps to Reproduce

1. Start App + DataStore
2. Wait until DataStore is ready
3. Navigate to homescreen and fetch data

Or.

1. Login Screen -> Login
2. Switch to loading to sync DataStore and wait until ready
3. Navigate to homescreen and fetch data

Screenshots

No response

Platforms

• iOS
• Android
• Web
• macOS
• Windows
• Linux

Flutter Version

3.29.3

Amplify Flutter Version

2.6.0

Deployment Method

Amplify CLI (Gen 1)

Schema

[tyllark]

Hello @JncHrmn, thank you for the detailed report. We will attempt to reproduce the issue and get back to you here with some guidance.

[JncHrmn]

@tyllark thanks for looking into this. I wanted to give you a quick status update on our internal testing efforts and share some additional context:

We shipped Ad-Hoc build to real iPhones. DataStore sync now behaves as expected. We see the full initial sync complete, queries return the correct data after the splash/loading screen, and changes made offline are properly pushed once connectivity returns.
We still see intermittent timing/race issues under the simulator, but as long as it works in "production", this is fine I guess.

Unfortunately, on Android physical devices DataStore appears to be entirely non-functional. During/After the login the sequence of DataStore.clear() and DataStore.start() is firing and it seems that it is successful as well. At this point CRUD operations on the models are possible. But after closing and cold-restarting the app, all models return empty lists—no data is ever pulled down or pushed up and any new entries created in the app are written locally but never synchronized to the cloud. When re-opening the app again, the created data is lost. The only option to get back into a functional state is only by logging out and logging in again.

I hope this helps and thanks again for the support!

[tyllark]

Hello @JncHrmn, DataStore does not sync data on startup, so you would need to call a function such as Amplify.DataStore.start() to trigger a sync and the DataStore ready event on startup. From our docs:

Each time DataStore starts (via start or any other operation: query, save, delete, or observe), DataStore will reevaluate the syncExpressions.

As for your data not syncing could you please update your DataStore Hub events to include these logging statements to help us understand the status of the DataStore Outbox.

Amplify.Hub.listen(HubChannel.DataStore, (hubEvent) {
      String hubPayload = 'No HubPayload';
      switch (hubEvent.type) {
        case DataStoreHubEventType.ready:
          break; //No Payload
        case DataStoreHubEventType.networkStatus:
          final payload = hubEvent.payload as NetworkStatusEvent?;
          hubPayload = 'active: ${payload?.active}';
        case DataStoreHubEventType.subscriptionsEstablished:
          break; //No Payload
        case DataStoreHubEventType.syncQueriesStarted:
          final payload = hubEvent.payload as SyncQueriesStartedEvent?;
          hubPayload = 'models: ${payload?.models}';
        case DataStoreHubEventType.modelSynced:
          final payload = hubEvent.payload as ModelSyncedEvent?;
          hubPayload =
              'modelName: ${payload?.modelName}, isFullSync: ${payload?.isFullSync}, isDeltaSync: ${payload?.isDeltaSync}, added: ${payload?.added}, updated: ${payload?.updated}, deleted: ${payload?.deleted}';
        case DataStoreHubEventType.syncQueriesReady:
          break; //No Payload
        case DataStoreHubEventType.outboxMutationEnqueued:
          final payload = hubEvent.payload as OutboxMutationEvent?;
          hubPayload =
              'modelName: ${payload?.modelName}, elementType: ${payload?.element.model.runtimeType}';
        case DataStoreHubEventType.outboxMutationProcessed:
          final payload = hubEvent.payload as OutboxMutationEvent?;
          hubPayload =
              'modelName: ${payload?.modelName}, elementType: ${payload?.element.model.runtimeType}';
        case DataStoreHubEventType.outboxMutationFailed:
          break; //No Payload
        case DataStoreHubEventType.outboxStatus:
          final payload = hubEvent.payload as OutboxStatusEvent?;
          hubPayload = 'isEmpty: ${payload?.isEmpty}';
        case DataStoreHubEventType.subscriptionDataProcessed:
          final payload = hubEvent.payload as SubscriptionDataProcessedEvent?;
          hubPayload =
              'modelName: ${payload?.modelName}, elementType: ${payload?.element.model.runtimeType}, version: ${payload?.element.version}, lastChangedAt: ${payload?.element.deleted}, elementType: ${payload?.element.deleted}';
      }

      safePrint('DataStoreEvent - ${hubEvent.eventName} - $hubPayload');
    });

On my side I'm able to Update my DynamoDB table and sync without issue on my Physical Android device:

networkStatus - active: true
outboxStatus - isEmpty: true
outboxMutationEnqueued - modelName: Todo, elementType: Todo
outboxStatus - isEmpty: false
subscriptionsEstablished - No HubPayload
syncQueriesStarted - models: [Todo]
modelSynced - modelName: Todo, isFullSync: false, isDeltaSync: true, added: 0, updated: 0, deleted: 0
syncQueriesReady - No HubPayload
ready - No HubPayload
outboxStatus - isEmpty: false
subscriptionDataProcessed - modelName: Todo, elementType: Todo, version: 1, lastChangedAt: false, elementType: false
outboxMutationProcessed - modelName: Todo, elementType: Todo
3x outboxStatus - isEmpty: true
outboxStatus - isEmpty: true
subscriptionsEstablished - No HubPayload
syncQueriesStarted - models: [Todo]
104x subscriptionDataProcessed - modelName: Todo, elementType: Todo, version: 1, lastChangedAt: false, elementType: false
syncQueriesReady - No HubPayload
modelSynced - modelName: Todo, isFullSync: true, isDeltaSync: false, added: 104, updated: 0, deleted: 0
ready - No HubPayload
outboxStatus - isEmpty: true

[JncHrmn]

@tyllark Sorry for the late reply. So we did more testing with the android setup. We started testing only on the simulator and added the print statements you provided. There was nothing unusual and everything worked as intended. Then we started simulating on a real device but still connect to the PC via cable. This also worked as intended, especially with your comment in mind, on how the datastore starts the sync process. We even build a debug apk file and distributed them to a few team members. The app was noticeable slower (flutter related), but the datastore seemed to work. Local data was there after app starts and syncing with the cloud did also work. Logging in and out always loaded the data of the user.

Now we uploaded the app to the app store for beta testing and release. In both cases, the app is not usable at all. All the problems that were described before are happening there. User logs in for the first time. Datastore is running (models synced etc.) and the user can create entries, update or delete them. But the moment the app is closed and reopened, nothing seems to work. If a user creates an other entry and we would fully close the app and open it again. All the data from before is gone. Meaning query data or creating is not syncing or refetching is always providing empty lists, even though there is data for this given user in the DB.
It feels strange, that the moment the app "enters" the play store, something with the datastore seems to break.
We couldn't provide any print outs so far, but if this is necessary for you to further proceed, we try to add a solution.