Maaz Zindani

Loading the index…

↑↓ move↵ openesc close4072 pages
Flutter and app store releases

Flutter assertion: ScrollController attached to multiple scroll views

ErrorScrollController attached to multiple scroll views.

Short answer

The assertion fires when code reads the controller's single position, such as offset, jumpTo or animateTo, while two scrollables are attached to it. Either you passed one controller to two widgets, or two lists without controllers both grabbed the primary one. Give each list its own controller, or set primary to false.

  • Applies to Flutter 3.3x stable, Dart 3.x
  • Updated
  • By Maaz Zindani, Senior Software Engineer

Fix it fast

  1. 1Find out which cause you have

    List every place a ScrollController is created or passed, then check which of those widgets are on screen at the same time.

    grep -rn "ScrollController\|primary:" lib
  2. 2Match what you see, then jump to its fix

    1. 1The same variable appears in the controller argument of two ListView, GridView or SingleChildScrollView widgetsOne controller is passed to two scrollablesFix
    2. 2No explicit controller is shared, but two vertical lists are visible at once, typically on web or desktopTwo lists with no controller inherit the same primary controllerFix

What does the error look like?

  • ScrollController attached to multiple scroll views.
  • 'package:flutter/src/widgets/scroll_controller.dart': Failed assertion: '_positions.length == 1'

Cause 1 of 2

One controller is passed to two scrollables

1Check

A controller makes one ScrollPosition per attached scrollable. Reading offset or calling jumpTo is only valid when exactly one position is attached, and positions lists them all.

grep -rn "controller: _\w*[cC]ontroller" lib

2Fix

Create one controller per scrollable. If you want two lists to move together, listen to one and jump the other, instead of sharing the object.

final _leftController = ScrollController();
final _rightController = ScrollController();

ListView(controller: _leftController, children: left)
ListView(controller: _rightController, children: right)

3Verify

Open the screen, scroll both lists, and trigger the code that read offset; no assertion appears.

flutter run

Confirmed by api.flutter.dev

Did this fix it?

Cause 2 of 2

Two lists with no controller inherit the same primary controller

1Check

A scroll view without its own controller can inherit the PrimaryScrollController of its route. Flutter's common-errors page says the clash is more likely on web and desktop than on mobile.

grep -rn "PrimaryScrollController" lib

2Fix

Mark the secondary list as not primary, or give it its own controller. A scroll view cannot be primary and have a controller at the same time.

ListView(
  primary: false,
  children: items,
)

3Verify

Resize the window or run on web so both lists show, then scroll each one.

flutter run -d chrome

Confirmed by api.flutter.dev

Did this fix it?

How do I stop it coming back?

  • Give every scrollable that shows together its own controller, and dispose each one.
  • Set primary: false on nested or side-by-side lists.
  • Test list screens on web or desktop, where several lists are easier to show at once.

Sources

How was this page made?

I drafted this page with AI assistance from the official documents listed under Sources. Every cause above names the document that confirms it. I have not reproduced this fix on a machine of my own yet, so read it as documented guidance, not a test report. Found a mistake? Tell me.

Which stack is behind this page?

Projects of mine built on the same technologies:

Related fixes

Next step

Want this handled for good?

I look after servers, apps and releases end to end. Tell me what keeps breaking.