Maaz Zindani

Loading the index…

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

Dart says the receiver can be null when I read a Firestore field with [ ]

ErrorThe 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.

  • Applies to Dart 3.9, Flutter 3.35, cloud_firestore (current docs)
  • Updated
  • By Maaz Zindani, Senior Software Engineer

Fix it fast

  1. 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 analyze
  2. 2Match what you see, then jump to its fix

    1. 1The failing line looks like doc.data()['name'] or snapshot.data()['name']DocumentSnapshot.data() can return nullFix
    2. 2snapshot.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. 3The 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

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 analyze

Confirmed by pub.dev

Did this fix it?

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 analyze

Confirmed by api.flutter.dev

Did this fix it?

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 analyze

Confirmed by dart.dev

Did this fix it?

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:

Related fixes

Next step

Want this handled for good?

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