Maaz Zindani

Loading the index…

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

Flutter: Null check operator used on a null value

ErrorNull check operator used on a null value

Short answer

The exclamation mark tells Dart a value is not null and throws if it is. The error means a value you asserted was still null at that moment. Find the line in the stack trace, then check the value first, give it a fallback, or wait for the data before reading it.

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

Fix it fast

  1. 1Find out which cause you have

    Open the first stack trace line that points at your own code in lib/. The ! on that line is the one that failed.

    flutter run --verbose
  2. 2Match what you see, then jump to its fix

    1. 1The error appears while a screen first draws, before the data has loadedData is read before it has arrivedFix
    2. 2The ! sits on a map lookup, a lookup result or an optional fieldA nullable value is asserted when null is a normal caseFix
    3. 3The failing line reads key.currentState! or key.currentContext!A GlobalKey has no state yetFix
    4. 4The code has if (_value != null) and then _value! further downA field is asserted after you checked itFix

What does the error look like?

  • Null check operator used on a null value

Cause 1 of 4

Data is read before it has arrived

1Check

Futures and streams deliver their data later. Until then the value is null, and a FutureBuilder starts with null data unless you set initialData.

grep -rn "snapshot\.data!" lib/

2Fix

Test for data before using it and show something else while waiting.

builder: (context, snapshot) {
  final data = snapshot.data;
  if (data == null) {
    return const CircularProgressIndicator();
  }
  return Text(data.title);
},

3Verify

Restart the app; the spinner shows first and the error is gone.

flutter run

Confirmed by api.flutter.dev

Did this fix it?

Cause 2 of 4

A nullable value is asserted when null is a normal case

1Check

The ! operator always throws when the value is null. If null can legitimately happen, the assertion turns a normal case into a crash.

grep -rn "[a-zA-Z_)\]]!\." lib/ | head -30

2Fix

Use ?. to skip the call, or ?? to give a fallback value.

final label = user?.name ?? 'Guest';

3Verify

The code runs with a null value and shows the fallback.

flutter test

Confirmed by dart.dev

Did this fix it?

Cause 3 of 4

A GlobalKey has no state yet

1Check

currentState is null when no widget with that key is in the tree, or when that widget has no State of the expected type.

grep -rn "currentState!" lib/

2Fix

Make sure the keyed widget is built before you use the key, and read the state with a null check.

final form = _formKey.currentState;
if (form != null && form.validate()) {
  // submit
}

3Verify

Tap the button before and after the form is visible; no exception is thrown.

flutter run

Confirmed by api.flutter.dev

Did this fix it?

Cause 4 of 4

A field is asserted after you checked it

1Check

Dart narrows local variables after a null check, but not fields that can change. Another piece of code may set the field to null in between.

grep -rn "!= null" lib/ | head -20

2Fix

Copy the field into a local variable and test that.

final value = _value;
if (value != null) {
  print(value.length);
}

3Verify

Run the same path; no assertion is needed and none is thrown.

dart analyze

Confirmed by dart.dev

Did this fix it?

How do I stop it coming back?

  • Treat every ! in a code review as a question: can this value really be null?
  • Use initialData or a loading state for every FutureBuilder and StreamBuilder.
  • Use a nullable type in your models for fields that the server may leave out.

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.