google_maps_flutter shows a blank or grey map
The map area is blank or grey with the Google logo missingShort answer
A blank GoogleMap is almost always one of three things: the Maps API key is not in the platform config, the Maps SDK for that platform is not enabled in Google Cloud, or the widget sits in a parent with unbounded size. Check the key first, then the enabled SDKs, then give the map a bounded height.
Fix it fast
1Find out which cause you have
Run the app with logs on and look for Maps key or SDK messages from the platform before changing code.
flutter run -v2Match what you see, then jump to its fix
What does the error look like?
The map area is blank or grey with the Google logo missingThe map does not render when its parent has no bounded size
Cause 1 of 3
The API key is missing from the platform setup
1Check
The Android package reads the key from AndroidManifest.xml. On web, the Maps JavaScript API script in index.html needs the key.
grep -n "API_KEY\|maps.googleapis" android/app/src/main/AndroidManifest.xml web/index.html2Fix
Add the key inside the application element for Android, and the script tag in the head for web.
<!-- android/app/src/main/AndroidManifest.xml, inside <application> -->
<meta-data android:name="com.google.android.geo.API_KEY"
android:value="YOUR KEY HERE"/>
<!-- web/index.html, in <head> -->
<script src="https://maps.googleapis.com/maps/api/js?key=YOUR_API_KEY"></script>3Verify
Rebuild fully; hot reload does not pick up manifest changes.
flutter clean && flutter runConfirmed by pub.dev
Cause 2 of 3
The Maps SDK for the platform is not enabled
1Check
Each platform needs its own SDK turned on for the key's project in the Google developers console: Maps SDK for iOS for iOS, and the Maps JavaScript API for web.
echo open the Maps APIs page of your Google Cloud project2Fix
Enable the SDK for every platform you run, and use the key from that same project.
# Google Cloud console: APIs and services > enable the SDK for the platform3Verify
Restart the app and reload the map.
flutter runConfirmed by pub.dev
Cause 3 of 3
The map sits in a parent with unbounded size
1Check
The package says the GoogleMap widget should be used within a widget with a bounded size.
grep -rn "GoogleMap(" lib/2Fix
Give it a fixed height, or fill the available space with Expanded inside a Column.
SizedBox(
height: 300,
child: GoogleMap(
initialCameraPosition: const CameraPosition(
target: LatLng(37.42796, -122.08574),
zoom: 14,
),
),
)3Verify
The map renders at 300 logical pixels high.
flutter runConfirmed by pub.dev
How do I stop it coming back?
- Follow the platform README of google_maps_flutter_android, _ios and _web for every platform you ship.
- Keep keys in a build config, and restrict them in Google Cloud.
- Always give the map a bounded parent.
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.
- QistLockA NestJS and React SaaS driving an Android Device Owner agent that locks financed phones when payments lapse.
- Dispatch ProA real-time logistics platform: Flutter apps, Spring Boot services and a Kafka event pipeline on AWS.
Related fixes
Mobile apps
iOS app crashes: Google Maps SDK must be initialized via provideAPIKey
Google Maps SDK for iOS must be initialized via [GMSServices provideAPIKey:...] prior to use
The Maps SDK throws this when a Maps object is created before GMSServices.provideAPIKey has run.
3 causes, each with a fixMobile 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 fix