Maaz Zindani

Loading the index…

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

iOS app crashes: Google Maps SDK must be initialized via provideAPIKey

ErrorGoogle Maps SDK for iOS must be initialized via [GMSServices provideAPIKey:...] prior to use

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

  • Applies to Maps SDK for iOS 9.x, Xcode 26, Swift 6
  • Updated
  • By Maaz Zindani, Senior Software Engineer

Fix it fast

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

    1. 1The grep for provideAPIKey finds nothing, or only a commented-out lineThe key is never providedFix
    2. 2The call exists, but the crash still happens at launch or in a property initializerA Maps object is created before the key is providedFix
    3. 3The 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

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

Did this fix it?

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 lines

Confirmed by developers.google.cn

Did this fix it?

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

Did this fix it?

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

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 fix

Next step

Want this handled for good?

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