← Flutter / Dart

Flutter / Dart · 19 / 24

AsyncNotifier: loading, errors and retry

Verify a failed read and an explicitly requested second attempt.

  • Large
  • Advanced
  • 90 min

Prerequisites: Null safety, errors and Future, Riverpod: observe and change state, Clean MVVM, services and repositories

In this tutorial
  1. Define the boundary
  2. Set up the learning project
  3. Trace the successful outcome
  4. Observe failures deliberately
  5. Solve the extension
  6. Compare the solution
  7. Exercise and solution
  8. Project context and sources

Download learning package

Setup and verification

Flutter 3.41.5 or newer with Dart 3.11. Python 3 is also required for the common verification entry point. Extract the learning package into a new folder and run python3 run_checks.py there. The script copies the included files into a temporary learning directory. It verifies the example and then the supplied solution there, preserving the original files. Required packages are downloaded on the first run.

Verified on 2026-10-20 on Linux x86_64. The fake fails on its first read and returns data on the second attempt. Check the transition from error to data and the repository call count.

Asynchronous state has more than one valid value. An interface also needs to explain waiting and failure. The provider owns the state machine. A repository returns data or an error. Automatic retry is disabled in this learning project so each test can observe exactly one attempt.

Package contents and individual files

01Define the boundary

AsyncValue separates loading, data and failure. The notifier owns the read operation. The UI selects its message and retry action from that state. A guard prevents overlapping retries.

lib/model.dart · dartOpen file
import 'package:flutter_riverpod/flutter_riverpod.dart';

abstract interface class VehicleReader {
  Future<List<String>> read();
}

class DemoReader implements VehicleReader {
  int attempts = 0;
  @override
  Future<List<String>> read() async {
    attempts++;
    if (attempts == 1) throw StateError('Storage unavailable');
    return ['Family car'];
  }
}

final readerProvider = Provider<VehicleReader>((ref) => DemoReader());
final vehiclesProvider = AsyncNotifierProvider<Vehicles, List<String>>(
  Vehicles.new,
  retry: (_, _) => null,
);

class Vehicles extends AsyncNotifier<List<String>> {
  @override
  Future<List<String>> build() => ref.watch(readerProvider).read();
  Future<void> retry() async {
    state = const AsyncLoading();
    state = await AsyncValue.guard(() => ref.read(readerProvider).read());
  }
}

02Set up the learning project

Direct dependencies are pinned. Extract all files together and run flutter pub get. Do not use an existing app database for tests. Tests create and clean up their own data.

pubspec.yaml · yamlOpen file
name: learning_example
publish_to: none
environment:
  sdk: ">=3.11.0 <4.0.0"
dependencies:
  flutter:
    sdk: flutter
  flutter_riverpod: 3.3.1
  drift: 2.33.0
  path_provider: 2.1.5
dev_dependencies:
  flutter_test:
    sdk: flutter
flutter:
  uses-material-design: true

03Trace the successful outcome

The fake fails on its first read and returns data on the second attempt. Check the transition from error to data and the repository call count.

test/model_test.dart · dartOpen file
import 'package:flutter_test/flutter_test.dart';
import 'package:flutter_riverpod/flutter_riverpod.dart';
import 'package:learning_example/model.dart';

void main() {
  test(
    'failed read can be retried without recreating the repository',
    () async {
      final reader = DemoReader();
      final container = ProviderContainer(
        overrides: [readerProvider.overrideWithValue(reader)],
      );
      addTearDown(container.dispose);
      expect(container.read(vehiclesProvider).isLoading, isTrue);
      await expectLater(
        container.read(vehiclesProvider.future),
        throwsStateError,
      );
      expect(reader.attempts, 1);
      expect(container.read(vehiclesProvider).hasError, isTrue);
      await container.read(vehiclesProvider.notifier).retry();
      expect(container.read(vehiclesProvider).requireValue, ['Family car']);
      expect(reader.attempts, 2);
    },
  );
}

Run / check

flutter pub get
flutter test
Expected result

The fake fails on its first read and returns data on the second attempt. Check the transition from error to data and the repository call count.

04Observe failures deliberately

Change an expected number or state in the test. flutter test must fail. Restore the correct expectation afterwards. Distinguish a domain failure from a missing plugin or development environment.

05Solve the extension

Add a second record and verify both are returned after retry.

06Compare the solution

The repository contract stays unchanged. The solution extends the confirmed value and checks its complete order. An error remains an error instead of becoming an empty list.

Expected result

flutter test passes for the original example and the extended solution.

Your exercise

Add a second record and verify both are returned after retry.

Show the solution and explanation

The repository contract stays unchanged. The solution extends the confirmed value and checks its complete order. An error remains an error instead of becoming an empty list.

solution/model_test.dart · dartOpen file
import 'package:flutter_test/flutter_test.dart';
import 'package:flutter_riverpod/flutter_riverpod.dart';
import 'package:learning_example/model.dart';

void main() {
  test(
    'failed read can be retried without recreating the repository',
    () async {
      final reader = ExtendedReader();
      final container = ProviderContainer(
        overrides: [readerProvider.overrideWithValue(reader)],
      );
      addTearDown(container.dispose);
      expect(container.read(vehiclesProvider).isLoading, isTrue);
      await expectLater(
        container.read(vehiclesProvider.future),
        throwsStateError,
      );
      expect(reader.attempts, 1);
      expect(container.read(vehiclesProvider).hasError, isTrue);
      await container.read(vehiclesProvider.notifier).retry();
      expect(container.read(vehiclesProvider).requireValue, [
        'Family car',
        'Motorbike',
      ]);
      expect(reader.attempts, 2);
    },
  );
}

class ExtendedReader extends DemoReader {
  @override
  Future<List<String>> read() async {
    final rows = await super.read();
    return [...rows, 'Motorbike'];
  }
}

Project context and sources

This independent learning project explores a topic in this technology area. Project references provide a pinned revision as architectural context. They do not imply that every library or feature introduced here is already used in that application.