iOS app crashes: Google Maps SDK must be initialized via provideAPIKey
Google Maps SDK for iOS must be initialized via [GMSServices provideAPIKey:...] prior to useShort answer
The Maps SDK throws this when a Maps object is created before GMSServices.provideAPIKey has run. Call it exactly once, at the very start of the app, before any GMSMapView or other Maps object exists. If the app also uses Places, call GMSPlacesClient.provideAPIKey as well.
Fix it fast
1Find out which cause you have
Search the project for every place the key is provided and every place a map object is created. The key call must come first in time, so this shows which cause applies.
grep -rn "provideAPIKey" --include=*.swift --include=*.m . grep -rn "GMSMapView\|GMSPanoramaView\|GMSCameraPosition" --include=*.swift --include=*.m .2Match what you see, then jump to its fix
- 1
The grep for provideAPIKey finds nothing, or only a commented-out lineThe key is never providedFix - 2
The call exists, but the crash still happens at launch or in a property initializerA Maps object is created before the key is providedFix - 3
The call appears in several files, or the app uses Places and only the Maps key is providedThe key is provided more than once, or Places has its own call missingFix
- 1
What does the error look like?
Google Maps SDK for iOS must be initialized via [GMSServices provideAPIKey:...] prior to use
Cause 1 of 3
The key is never provided
1Check
The SDK has no key until your code hands it one. The setup guide puts the call in application(_:didFinishLaunchingWithOptions:). A SwiftUI app has no AppDelegate unless you add one, so the call is easy to forget there.
grep -rn "import GoogleMaps" --include=*.swift .2Fix
Import GoogleMaps and call provideAPIKey with your key before the first screen is built. In a SwiftUI app, do it in the App struct's init, or add an AppDelegate with UIApplicationDelegateAdaptor.
import SwiftUI
import GoogleMaps
@main
struct MyApp: App {
init() {
GMSServices.provideAPIKey("YOUR_API_KEY")
}
var body: some Scene {
WindowGroup { ContentView() }
}
}3Verify
Clean the build, run the app and open the screen with the map. It no longer terminates at launch.
xcodebuild clean build -scheme MyApp -destination 'generic/platform=iOS Simulator'Confirmed by developers.google.cn
Cause 2 of 3
A Maps object is created before the key is provided
1Check
The reference says the key must be provided before any Maps SDK object is initialized. A GMSMapView held in a stored property with a default value, or a singleton, is created while the app object is built, which can be earlier than your key call.
grep -rn "= GMSMapView\|GMSMapView(" --include=*.swift .2Fix
Move the provideAPIKey call to the earliest launch point, and create map objects lazily, inside a view or after launch, never in a global or static initializer.
final class MapScreen {
// created on first use, after launch has finished
lazy var mapView = GMSMapView()
}3Verify
Put a breakpoint on the provideAPIKey line and one where the map is created. The first must hit first.
# Xcode: Debug > Breakpoints > Create Symbolic Breakpoint, or click the gutter on both linesConfirmed by developers.google.cn
Cause 3 of 3
The key is provided more than once, or Places has its own call missing
1Check
The reference says provideAPIKey must be called exactly once. Places is a separate SDK, so it needs its own key call.
grep -rn "provideAPIKey" --include=*.swift --include=*.m .2Fix
Keep one GMSServices.provideAPIKey call. If you use Places, add GMSPlacesClient.provideAPIKey next to it.
GMSServices.provideAPIKey("YOUR_API_KEY")
GMSPlacesClient.provideAPIKey("YOUR_API_KEY")3Verify
Run the app and trigger the Places feature once.
grep -rn "provideAPIKey" --include=*.swift --include=*.m .Confirmed by developers.google.cn
How do I stop it coming back?
- Keep the key calls in one file, the app entry point, and nowhere else.
- Never create a GMSMapView in a global, static or default property value.
- Restrict the key to your app's bundle identifier in Google Cloud so a leaked key is useless elsewhere.
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
Mobile apps
UserDefaults logs 'Failed to read values in CFPrefsPlistSource' for an app group
Settings saved by the app are not visible to its extension, widget or sibling app that share the group
This log comes from the preferences system when UserDefaults is opened for an app group's suite.
3 causes, each with a fixMobile apps
UIKit app crashes because it cannot find the storyboard
Could not find a storyboard named 'Main' in bundle NSBundle
UIStoryboard throws this exception when no storyboard file with that name exists in the bundle it searches.
3 causes, each with a fixMobile apps
Firebase on iOS asks for the FCM token before APNs has given one
Be sure to re-retrieve the FCM token once the APNS device token is set.
The Firebase Messaging SDK needs the APNs device token from iOS before it hands out an FCM token.
3 causes, each with a fixMobile apps
A test push from the Firebase console never shows up on the iPhone
didReceiveRegistrationToken prints a token, yet no notification arrives
When a console message is accepted but the iPhone stays silent, the break is between Firebase and APNs or inside the app.
4 causes, each with a fixMobile apps
InstanceID token() no longer works in a Swift Firebase app
Instance ID calls fail to compile after upgrading Firebase to 8.0.0 or later
Firebase removed the Instance ID dependency from Messaging in 8.0.0, so InstanceID.instanceID() calls no longer belong in a current app.
3 causes, each with a fixMobile apps
iOS launch screen with an asset catalog image or color does not appear
The launch image from the asset catalog never shows
iOS shows a launch screen only if the target defines one: a UILaunchScreen entry in Info.plist, or a launch storyboard chosen for the target.
3 causes, each with a fix