Dart says the receiver can be null when I read a Firestore field with [ ]
The method '[]' can't be unconditionally invoked because the receiver can be 'null'.Short answer
Dart's null safety refuses to use [ ] on a value that may be null. In Firestore code the nullable value is usually DocumentSnapshot.data(), which returns T?, or AsyncSnapshot.data inside a StreamBuilder or FutureBuilder. Check for null first, put the value in a local variable, or use the null-aware ?[ ] and ?. forms.
Fix it fast
1Find out which cause you have
Run the analyzer and open the line it names. Find the expression to the left of the [ ]. Its type, shown on hover in your editor, ends in a question mark: that is the nullable value to deal with.
flutter analyze2Match what you see, then jump to its fix
- 1
The failing line looks like doc.data()['name'] or snapshot.data()['name']DocumentSnapshot.data() can return nullFix - 2
snapshot.data['name'] inside a builder, even right after a snapshot.hasData checksnapshot.data inside StreamBuilder or FutureBuilder is nullable, and hasData does not promote itFix - 3
The nullable value is a Map<String, dynamic>? that you declared, for example a class field filled in laterYour own Map variable or field is declared nullableFix
- 1
What does the error look like?
The method '[]' can't be unconditionally invoked because the receiver can be 'null'.The operator '[]' can't be unconditionally invoked because the receiver can be 'null'.
Cause 1 of 3
DocumentSnapshot.data() can return null
1Check
In the cloud_firestore API, data() is declared as T? data(). The question mark in the type means the call may return null, and the analyzer's own advice for such a value is to test it before use.
grep -rn "\.data()\[" lib/2Fix
Use the null-aware index operator for a one-off read, or move the map into a local variable and test it once if you need several fields.
final doc = await FirebaseFirestore.instance.collection('users').doc(uid).get();
// one field
final name = doc.data()?['name'] as String?;
// several fields
final data = doc.data();
if (data != null) {
final name = data['name'] as String;
final age = data['age'] as int;
}3Verify
Run flutter analyze again. The message is gone, and the screen handles a missing document without a crash.
flutter analyzeConfirmed by pub.dev
Cause 2 of 3
snapshot.data inside StreamBuilder or FutureBuilder is nullable, and hasData does not promote it
1Check
AsyncSnapshot.data is declared as T?, and the docs say it is null when the snapshot holds an error. Dart only promotes local variables after a null check, and fields only when they are both private and final. snapshot.data is a public field of another object, so checking snapshot.hasData does not change its type.
grep -rn "snapshot.data" lib/2Fix
Copy the value into a local variable and test that, or chain null-aware calls. Show a loading or empty state when it is null.
StreamBuilder<DocumentSnapshot<Map<String, dynamic>>>(
stream: FirebaseFirestore.instance.collection('users').doc(uid).snapshots(),
builder: (context, snapshot) {
final data = snapshot.data?.data();
if (data == null) {
return const CircularProgressIndicator();
}
return Text(data['name'] as String);
},
)3Verify
The analyzer reports nothing, and the widget shows the loading state first and then the name.
flutter analyzeConfirmed by api.flutter.dev
Cause 3 of 3
Your own Map variable or field is declared nullable
1Check
The null-safety guide says that a nullable type allows no member access without a check, but null-aware operators work on it. It also says that fields do not promote after a null check unless they are private and final, so if (user != null) user['name'] still fails for a public or non-final field.
grep -rn "Map<String, dynamic>?" lib/2Fix
Use ?[ ] when a missing value is acceptable. For several reads, copy the field into a local variable first, then check that variable. Use ! only where you are sure the value is set, because it throws at runtime if you are wrong.
class ProfileState {
Map<String, dynamic>? user;
String? get name => user?['name'] as String?;
String describe() {
final u = user; // local copy, so the check promotes it
if (u == null) return 'no user';
return '${u['name']}, ${u['age']}';
}
}3Verify
Run the analyzer. Both the getter and the method pass.
flutter analyzeConfirmed by dart.dev
How do I stop it coming back?
- Type Firestore reads once, in one place (a fromMap constructor or a converter), and let the rest of the app use typed fields.
- Treat every data() call as possibly empty and decide what the screen shows for a missing document.
- Prefer a local variable over repeated snapshot.data lookups inside a builder.
- Use ! sparingly, and never on data that comes from the network.
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:
- TaxiDexMy own multi-tenant taxi dispatch SaaS: API, dispatcher portal, driver and passenger apps, and the servers underneath.
- Qist BazaarA buy-now-pay-later marketplace built from a blank repo, now past 100K downloads on Google Play.
- SessionBirdAn omnichannel engagement suite in Flutter: campaigns, chatbot, tickets, analytics and live calling.
Related fixes
Mobile apps
Flutter: Null check operator used on a null value
Null check operator used on a null value
The exclamation mark tells Dart a value is not null and throws if it is.
4 causes, each with a fixMobile apps
Reading a Firestore number into a Dart double throws a type error
TypeError
Firestore stores integers and floating-point numbers as separate types, and Dart keeps int and double apart too.
2 causes, each with a fixMobile apps
AudioCache has no play method after updating audioplayers
The method 'play' isn't defined for the type 'AudioCache'.
Since audioplayers 1.0, AudioCache only turns asset files into local files and caches them.
2 causes, each with a fixMobile apps
Flutter Bloc throws that emit was called after the event handler completed
emit was called after an event handler completed normally.
Each on<Event> handler gets its own Emitter, and it stops working the moment the handler's returned Future completes.
2 causes, each with a fixMobile apps
analysis_options.yaml: the URI it includes can't be found
include_file_not_found
The analyzer reports include_file_not_found when the file named after include: in analysis_options.yaml does not resolve.
2 causes, each with a fixMobile apps
Dart error: the body might complete normally and return null for a non-nullable type
body_might_complete_normally
Dart found a path through your function or callback that reaches the closing brace without a return.
3 causes, each with a fix