Firestore in Flutter throws 'Bad state: field does not exist within the DocumentSnapshotPlatform'
Unhandled Exception: Bad state: field "name" does not exist within the DocumentSnapshotPlatformShort answer
snapshot['field'] and snapshot.get('field') throw a StateError when the document has no such field, or when the document itself does not exist. They never return null. Read the map from data() and use null-aware access instead, and check snapshot.exists before touching a field of a document that may be absent.
Fix it fast
1Find out which cause you have
Print the whole map the snapshot holds. If the key you read is not in it, or the map is null, the cause is on the list below.
final snap = await FirebaseFirestore.instance.doc('users/abc').get(); print('exists: ${snap.exists}'); print('data: ${snap.data()}');2Match what you see, then jump to its fix
- 1
field "name" does not exist within the DocumentSnapshotPlatformThe document has no field with that exact nameFix - 2
cannot get field "name" on a DocumentSnapshotPlatform which does not existThe document itself does not existFix - 3
field "..." does not exist within the DocumentSnapshotPlatform, with a dotted path such as address.cityA nested path runs through a value that is not a mapFix
- 1
What does the error look like?
Unhandled Exception: Bad state: field "name" does not exist within the DocumentSnapshotPlatformBad state: cannot get field "name" on a DocumentSnapshotPlatform which does not exist
Cause 1 of 3
The document has no field with that exact name
1Check
Older documents, or documents written by another client or a script, often lack a field that newer code expects. Field names are matched exactly, so 'Name' and 'name' are different fields.
print(snap.data()?.keys.toList());2Fix
Read the field from the data map, so a missing key gives null, and give it a default.
final data = snap.data() as Map<String, dynamic>?;
final name = (data?['name'] as String?) ?? 'Unknown';3Verify
Open a document that lacks the field. The screen should show the default, with no exception in the console.
flutter runConfirmed by raw.githubusercontent.com
Cause 2 of 3
The document itself does not exist
1Check
A path with a typo, an id that was deleted, or a document not created yet gives a snapshot whose exists is false. The check above prints exists: false and data: null.
print(snap.exists);2Fix
Test exists first and show an empty or not-found state when it is false.
if (!snap.exists) {
return const Text('Profile not found');
}
final name = snap['name'];3Verify
Point the reference at an id that does not exist; the not-found state should show.
flutter runConfirmed by pub.dev
Cause 3 of 3
A nested path runs through a value that is not a map
1Check
get() accepts a dot-notated path or a FieldPath and walks it level by level. If 'address' is a string, a list or null, the next level cannot be found and the same StateError is thrown.
print(snap.data()?['address'].runtimeType);2Fix
Read level by level with null-aware operators and a type check, instead of a single dotted path.
final address = snap.data()?['address'];
final city = address is Map ? address['city'] as String? : null;3Verify
Run against a document with a missing or wrongly typed address; city should be null, not an exception.
flutter runConfirmed by raw.githubusercontent.com
How do I stop it coming back?
- Treat every field of a stored document as optional and give each a default when you read it.
- Map snapshots to a typed model in one place (fromFirestore) so null handling is written once.
- Check exists before reading from a document fetched by id.
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.
- Dispatch ProA real-time logistics platform: Flutter apps, Spring Boot services and a Kafka event pipeline on AWS.
- Qist BazaarA buy-now-pay-later marketplace built from a blank repo, now past 100K downloads on Google Play.
Related fixes
Mobile apps
Google Play says the app does not support 16 KB memory pages
check_elf_alignment.sh reports UNALIGNED for a library under lib/arm64-v8a
Google Play requires apps that target Android 15 or higher and ship native .so libraries to run on devices with 16 KB memory pages; from 1 February 2027 it will block updates that do not.
5 causes, each with a fixMobile apps
Gradle cannot find com.google.firebase:firebase-analytics-ktx
Required by: project :app
Firebase moved the Kotlin extensions into the main modules and stopped releasing the -ktx modules in July 2025.
2 causes, each with a fixMobile apps
Gradle cannot create LibraryVariantBuilderImpl in a Flutter Android build
Could not create an instance of type com.android.build.api.variant.impl.LibraryVariantBuilderImpl
This error appears when the Android Gradle plugin (AGP) cannot run in the Gradle or IDE you use.
3 causes, each with a fixMobile apps
Flutter release build cannot open the keystore: HmacPBESHA256 not available
Algorithm HmacPBESHA256 not available
The keystore is a PKCS12 file protected by a newer algorithm than the Java that is reading it understands.
3 causes, each with a fixMobile apps
Android install error: the package conflicts with an existing package of the same name
The package conflicts with an existing package by the same name
Android allows only one app per application ID, and an update must be signed with the same certificate as the installed version.
3 causes, each with a fixMobile apps
Android resource linking fails with resource android:attr/lStar not found
error: failed linking references.
The lStar attribute exists only from Android API 31.
2 causes, each with a fix