Maaz Zindani

Loading the index…

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

DropdownButton throws: there should be exactly one item with its value

ErrorThere should be exactly one item with [DropdownButton]'s value:

Short answer

DropdownButton asserts that, when its value is not null, exactly one item in its list has that value. The error fires when two items share a value, when the value is missing from the list, or when the list changed and the old value stayed. Make values unique and reset or null the value.

  • Applies to Flutter 3.35, Dart 3.9
  • Updated
  • By Maaz Zindani, Senior Software Engineer

Fix it fast

  1. 1Find out which cause you have

    Print the selected value and the item values side by side, right before the DropdownButton builds. The mismatch shows itself.

    debugPrint('value=$selected items=${items.map((e) => e.value).toList()}');
  2. 2Match what you see, then jump to its fix

    1. 1The printed list contains the same value twiceTwo items have the same valueFix
    2. 2value=... in the printed line does not appear in the items list (count of zero)The selected value is not one of the item valuesFix
    3. 3The error appears after you reload the list, change a filter or pick another parent dropdownThe items list changed but the old value stayedFix

What does the error look like?

  • There should be exactly one item with [DropdownButton]'s value:
  • Either zero or 2 or more [DropdownMenuItem]s were detected with the same value

Cause 1 of 3

Two items have the same value

1Check

The assertion counts the items whose value equals the selected value. Duplicates in your source list give a count of 2 and the assertion fails.

final values = items.map((e) => e.value).toList();
debugPrint('${values.length} items, ${values.toSet().length} distinct');

2Fix

Remove duplicates before you build the items, for example by turning the list into a set first.

final unique = options.toSet().toList();
DropdownButton<String>(
  value: selected,
  items: unique.map((o) => DropdownMenuItem(value: o, child: Text(o))).toList(),
  onChanged: (v) => setState(() => selected = v),
)

3Verify

Hot restart and open the dropdown: no assertion and each option shows once.

# press R in the flutter run terminal

Confirmed by raw.githubusercontent.com

Did this fix it?

Cause 2 of 3

The selected value is not one of the item values

1Check

A typical case: the initial value is a string such as 'Select' that you did not add as an item, or the value comes from a server with different spelling or case. When the type is an object, the value must also compare equal to one item, so define == and hashCode on that class or pass the object from the list itself.

debugPrint('${options.contains(selected)}');

2Fix

Start with null and show a hint, or start with a value that really is in the list.

DropdownButton<String>(
  value: options.contains(selected) ? selected : null,
  hint: const Text('Choose one'),
  items: options.map((o) => DropdownMenuItem(value: o, child: Text(o))).toList(),
  onChanged: (v) => setState(() => selected = v),
)

3Verify

Run the screen cold. It opens with the hint and no assertion.

flutter run

Confirmed by api.flutter.dev

Did this fix it?

Cause 3 of 3

The items list changed but the old value stayed

1Check

The value kept the old selection while the new list no longer has it, so zero items match.

// Find where items are replaced, and check whether selected is reset there
grep -rn "setState" lib/ | grep -i "items\|options"

2Fix

Reset the value to null whenever the list is replaced, in the same setState call.

setState(() {
  options = newOptions;
  selected = null;
});

3Verify

Change the list again. The dropdown shows its hint and no error.

# repeat the filter change in the running app

Confirmed by raw.githubusercontent.com

Did this fix it?

How do I stop it coming back?

  • Keep the options in one list and derive every DropdownMenuItem from it.
  • Store a null selection plus a hint instead of a fake first value.
  • For objects, store an id or override == and hashCode on the class.

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.