riverpod-ref-listen-build-only

Riverpod ref.listen Must Be in build() for ConsumerStatefulWidget

Problem

In Riverpod 3.x, calling ref.listen inside initState(), addPostFrameCallback, or any method other than build() causes an assertion failure:

ref.listen can only be used within the build method of a ConsumerWidget
'package:flutter_riverpod/src/core/consumer.dart':
Failed assertion: line 492 pos 7: 'debugDoingBuild'

This typically manifests when trying to reactively watch a provider value that may change after the widget is first built (e.g., waiting for an async operation to complete).

Context / Trigger Conditions

• Using ConsumerStatefulWidget with flutter_riverpod: ^3.0.0
• Calling ref.listen(provider, callback) inside initState() or a post-frame callback
• All widget tests fail with the assertion error from ConsumerStatefulElement.listen
• The error occurs during pumpWidget or pumpAndSettle in tests
• Stack trace shows SchedulerBinding._invokeFrameCallback -> ConsumerStatefulElement.listen

Solution

Move ref.listen into the build() method. Use a guard flag to ensure side effects only trigger once.

Before (broken):

class _MyScreenState extends ConsumerState<MyScreen> {
  @override
  void initState() {
    super.initState();
    WidgetsBinding.instance.addPostFrameCallback((_) {
      // THIS WILL CRASH in Riverpod 3.x
      ref.listen(
        myProvider.select((s) => s.someValue),
        (previous, next) {
          if (previous == null && next != null) {
            _doSomething(next);
          }
        },
      );
    });
  }
}

After (fixed):

class _MyScreenState extends ConsumerState<MyScreen> {
  bool _actionAttempted = false;

  @override
  void initState() {
    super.initState();
    WidgetsBinding.instance.addPostFrameCallback((_) {
      if (!mounted) return;
      // Immediate check for already-available data
      final value = ref.read(myProvider).someValue;
      if (value != null) _tryDoSomething(value);
    });
  }

  void _tryDoSomething(SomeType? value) {
    if (value == null || _actionAttempted) return;
    _actionAttempted = true;
    _doSomething(value);
  }

  @override
  Widget build(BuildContext context) {
    // ref.listen is safe here - Riverpod auto-manages the subscription
    ref.listen(
      myProvider.select((s) => s.someValue),
      (previous, next) {
        if (previous == null && next != null) {
          _tryDoSomething(next);
        }
      },
    );

    return // ... widget tree
  }
}