Riverpod Ref Listen Build Only

What it does

When your agent uses it

• ConsumerStatefulWidget crashes with Failed assertion: line 492 pos 7: debugDoingBuild in flutterriverpod consumer.dart
• Ref.listen is called inside initState
• AddPostFrameCallback
• Any lifecycle method other than build()

Example prompts

• “Failed assertion: line 492 pos 7:”
• “/riverpod-ref-listen-build-only”

Workflow steps

5 steps, taken from the first numbered list in SKILL.md.

1. 1ref.listen in build() is auto-managed by Riverpod (no manual disposal needed)
2. 2It re-registers each build but Riverpod handles deduplication
3. 3Use a guard flag (_actionAttempted) to prevent side effects from firing multiple times
4. 4Keep the immediate check in initState's post-frame callback for when data is already available
5. 5ref.read is fine in initState/callbacks; only ref.listen and ref.watch are restricted

What it can do on your machine

Read from SKILL.md and the folder at commit 6487b05. It shows what the files ask for, not the result of running them.

• Tool permissions

  Pre-approves nothing: there is no allowed-tools line, so your agent's usual permission prompts apply.

  From allowed-tools in the SKILL.md frontmatter.

• Runs code

  No scripts in the folder and no shell commands in SKILL.md (its code samples are dart).

  From the folder's file list and the shell code blocks in SKILL.md.

• Network

  Links to these hosts (documentation or services it may open):

  • riverpod.dev
  • pub.dev

  From URLs in SKILL.md, links to its own repository left out.

• Credentials

  Names no API keys, tokens, secrets or passwords.

  From names ending in _API_KEY, _TOKEN, _SECRET, _KEY or _PASSWORD in SKILL.md.

Context cost

Riverpod Ref Listen Build Only loads about 1.1k tokens when it runs. Until then it costs about 133 tokens; SKILL.md has 277 words of instructions outside code blocks.

Always · name and description, kept in context so the agent knows when to use it

~133

When it runs · the whole SKILL.md, loaded when a task matches

~1.1k

Estimates: characters ÷ 4, the usual rule of thumb; real counts depend on the model's tokenizer. Scripts and assets cost tokens only if the agent reads them.

Safety

Automated static check — not a guarantee. Review scripts before installing. It scans the text of SKILL.md for risky patterns (piping downloads into a shell, reading credential files, hidden Unicode, destructive commands); files beside SKILL.md are not scanned.

SKILL.md

The full file from divinevideo/divine-mobile at commit 6487b05, republished under its MPL-2.0 licence (© divinevideo). 277 words, ~1,110 tokens.

name

riverpod-ref-listen-build-only

description

Fix "ref.listen can only be used within the build method of a ConsumerWidget" assertion error in Flutter Riverpod 3.x. Use when: (1) ConsumerStatefulWidget crashes with "Failed assertion: line 492 pos 7: 'debugDoingBuild'" in flutter_riverpod consumer.dart, (2) ref.listen is called inside initState, addPostFrameCallback, or any lifecycle method other than build(), (3) All widget tests fail with this assertion from scheduler callback. Applies to flutter_riverpod 3.0+ with ConsumerStatefulWidget.

author

Claude Code

version

1.0.0

date

2026-02-06

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'

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);
          }
        },
      );
    });
  }
}

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
  }
}

© divinevideo, MPL-2.0. Rendered from Markdown: HTML in the file is shown as text, images as links, and headings moved down two levels. Raw file

Files

Just SKILL.md in .agents/skills/riverpod-ref-listen-build-only of divinevideo/divine-mobile.

Open the folder on GitHubat commit 6487b05