Bad State: No Element — Guard firstWhere

Your list screen works for months, then one user with an empty inbox opens it and meets a red screen: Bad state: No element. No network failure, no corrupt data — just a search across zero items. FirstWhere, singleWhere, first, and last all throw this identical tantrum when there is nothing to return, and the stack points at a line that looked perfectly safe during development.

The trap is sample data. Developers build against lists that always contain the sought item, so the miss path never executes until production supplies an empty cart, a filtered-to-zero search, or a deleted record the cache still references. The throw happens synchronously inside build, which means no error boundary of async handling catches it — the frame dies and the red screen takes over.

This guide hardens every lookup. You will learn which methods throw and why, how orElse converts misses into fallbacks, when singleWhere's duplicate error bites, which empty-list guards belong before every read, and how nullable search patterns keep intent clear. By the end, empty data will render empty states instead of exceptions.

Which Calls Throw and Exactly Why

Four call shapes share one tantrum. FirstWhere throws when no element satisfies the predicate — the classic filter miss. First and last throw on empty collections, since there is no position zero or final position to return. SingleWhere throws on zero matches like firstWhere, and on two or more matches, because its contract promises exactly one. Indexing an empty list throws RangeError instead, a close cousin worth guarding in the same pass.

All four throw synchronously at the call site. Inside build that means the frame aborts to the red error screen; inside event handlers it unwinds to the nearest catch or crashes the zone. There is no async boundary to soften it and no null to check downstream — the method never returns on the miss path. Developers who expect a null result write code after the call that never executes, compounding the confusion.

Learn to spot the shapes in review. A firstWhere without a trailing orElse argument is an unhandled miss path. A .first or .last with no isEmpty guard above it is an unhandled empty path. A singleWhere on data without a uniqueness proof is an unhandled duplicate path. Each shape takes seconds to recognize and minutes to harden — the cheapest review comments you will ever leave.

void main() {
  final List<String> inbox = <String>[];
  // Each line below throws on this input: no element to return.
  // inbox.firstWhere((m) => m.startsWith('Hi')); // Bad state: No element
  // inbox.first; // Bad state: No element
  // inbox.last; // Bad state: No element
  // inbox.singleWhere((m) => m.isNotEmpty); // Bad state: No element
  // Hardened versions appear in the next sections.
  assert(inbox.isEmpty, 'repro input must be empty');
}

orElse: Turning Misses Into Fallbacks

The orElse callback is the designed answer to the miss path: return a fallback element when nothing matches, and the method never throws. A checkout resolving a possibly deleted address supplies a fallback that routes to the picker; a theme lookup supplies the default theme; a settings read supplies factory defaults. The UI already knows how to render these states — orElse simply lets the miss reach them instead of dying mid-build.

Choose fallbacks that preserve user momentum. A deleted-address fallback that opens the address picker with a notice keeps checkout moving; a fallback that silently substitutes another user's address corrupts orders. The fallback runs only on misses, so make it cheap and side-effect free — no network calls inside orElse, just a value selection. Expensive recovery belongs in the UI branch the fallback triggers, not in the callback.

Apply orElse universally, not just at the crashed site. After any No element incident, search the codebase for every firstWhere lacking the argument — each is the same bug with a different predicate. Fixing one while leaving twenty is incident scheduling, not incident response. The review rule is absolute: no firstWhere merges without orElse, no exceptions, no todos. Automate the check and the rule enforces itself.

class Address {
  const Address(this.id, this.label);
  final String id;
  final String label;
}

const Address pickFallback = Address('new', 'Choose an address');

Address resolveDefault(List<Address> saved, String cachedId) {
  // Misses return the picker fallback instead of throwing.
  return saved.firstWhere(
    (Address a) => a.id == cachedId,
    orElse: () => pickFallback,
  );
}

void main() {
  final Address got = resolveDefault(const <Address>[], 'deleted-id');
  assert(got.id == 'new', 'misses must route to the picker');
}

singleWhere Duplicates and first-last Guards

SingleWhere promises exactly one match, so it throws twice: zero matches produce No element, two or more produce Too many elements. The duplicate error surprises teams that proved uniqueness once and watched imports, merges, or race conditions quietly duplicate rows. If your data cannot prove uniqueness at the call site — a database constraint, a Set-backed structure — singleWhere is a promise you cannot keep.

Downgrade deliberately when any-match suffices. FirstWhere with orElse expresses honestly that duplicates are tolerable and misses have fallbacks, surviving both error shapes. Keep singleWhere only where duplicates indicate corruption worth crashing over in debug and catching in production — and even then, wrap the call so the corruption renders diagnostics instead of red.

First and last need the humble isEmpty guard. Check emptiness before reading and return the designed empty state: the illustration, the invite button, the zero balance. Guards belong directly above the read, not three frames up the call stack, so future readers see the contract locally. Index access shares the rule — verify indices against length before subscripting lists that async gaps can shrink. Co-locating guard and read keeps the contract visible through every future refactor.

import 'package:flutter/material.dart';

class InboxHeadline extends StatelessWidget {
  const InboxHeadline({super.key, required this.messages});
  final List<String> messages;

  @override
  Widget build(BuildContext context) {
    // Guard directly above the read: empty renders, never throws.
    if (messages.isEmpty) return const Text('Inbox zero. Enjoy the calm.');
    final String latest = messages.first;
    final String oldest = messages.last;
    return Text('Latest: $latest / Oldest: $oldest');
  }
}

Nullable Search Patterns for Honest Misses

Some searches legitimately find nothing, and the code should say so in its types. A manual loop returning a nullable result expresses the miss honestly: found means an element, null means absence, and every caller handles both because the compiler insists. This pattern suits heterogeneous fallback logic where orElse's single value cannot capture what the UI must do next.

IndexWhere plus an index check is the list-position sibling: search for the position, compare against -1, and branch explicitly. It shines when callers need the position itself — highlighting the found row, scrolling to it, or replacing it. The -1 branch is the designed miss path, as visible as orElse and equally unthrowing.

Keep the patterns boring and local. A tiny private helper per screen beats a clever generic extension that future readers must decode, and explicit branches beat sentinel values that conflate missing with real data. Misses are normal application states — empty inboxes, cleared carts, deleted records — so their code should read as calmly as the empty-state illustration looks. Boring miss handling is the hallmark of production-ready lookup code. Reviewers should praise calm fallbacks, not clever queries.

class Member {
  const Member(this.id, this.name);
  final String id;
  final String name;
}

// Honest miss: null means absent, and callers must handle it.
Member? findMember(List<Member> members, String id) {
  for (final Member m in members) {
    if (m.id == id) return m;
  }
  return null;
}

int whereMember(List<Member> members, String id) {
  return members.indexWhere((Member m) => m.id == id); // -1 means absent
}

void main() {
  const List<Member> team = <Member>[Member('a', 'Ada')];
  assert(findMember(team, 'zzz') == null, 'misses return null');
  assert(whereMember(team, 'zzz') == -1, 'miss index is -1');
}

Stale Caches: Validating Ids Before Lookup

The nastiest misses come from ids that were valid yesterday. Mobile caches outlive the records they reference: addresses deleted on the web, cards removed by support, products delisted overnight. The lookup code is correct against fresh data and explosive against reality — the gap between cache time and lookup time is where No element breeds.

Validate at the boundary, not at the crash. When checkout opens, reconcile cached ids against the fresh fetch: drop dangling references, clear them from storage, and fall through to the picker before any firstWhere runs. This converts a crash into a minor inconvenience — reselect an address — at the moment the user can best absorb it, rather than mid-payment where trust is thinnest.

Design caches with deletion in mind from the start. Store the fetched-at timestamp alongside ids, revalidate selections older than the session on entry to critical flows, and listen for deletion events that proactively purge references. Caches are performance tools, not source-of-truth — every cached id is a hypothesis the next fetch may falsify, and lookup code must survive falsification gracefully. Purge-on-delete beats crash-on-read in every postmortem. Design for deletion from day one.

class Address {
  const Address(this.id, this.label);
  final String id;
  final String label;
}

// Reconcile cached ids against fresh data before any lookup runs.
List<Address> reconcile(List<Address> fresh, List<String> cachedIds) {
  final Set<String> live = <String>{for (final Address a in fresh) a.id};
  final List<String> stale = cachedIds.where((String id) => !live.contains(id)).toList();
  for (final String id in stale) {
    dropCachedId(id); // purge the dangling reference once
  }
  return fresh;
}

void dropCachedId(String id) {
  // Delete id from local storage; stubbed for this sample.
  assert(id.isNotEmpty);
}

Locking It With Empty, Miss, and Duplicate Tests

Three fixtures harden every lookup: the empty collection, the populated collection with no match, and the collection with duplicates. Pump the widget once per fixture and assert the designed outcome — empty illustration, fallback content, first-match rendering — plus tester.takeException is null throughout. This trio covers both throw shapes and the guard paths in under twenty lines per call site.

Name tests after the miss, not the method. Test titles like dangling address id routes to picker document the contract for future readers, while firstWhere test says nothing about intent. When a new developer changes the lookup, the failing test title explains the requirement instead of merely announcing a breakage.

Run the trio in CI for every screen that searches. Lookup regressions arrive disguised as data changes — a backend that starts returning empty arrays, an import that duplicates rows — and only fixture tests catch them before users do. Screens covered by the trio render empty states with the same polish as their populated states, because both are tested with equal seriousness. Empty is a first-class state, so test it like one. Fixtures this small pay for themselves on the first data change.