What Is google-services.json? Placement, Updates, and Project Checks

google-services.json is the configuration file that connects an Android app to a Firebase project.

Using the wrong file can cause not only build errors but also connections to an unintended Firebase project.

Typical symptoms include:

• Firestore data does not appear where expected
• Users are created in another Firebase project
• Google Sign-In fails
• Firebase Cloud Messaging notifications do not arrive
• No matching client found for package name appears
• google-services.json is missing appears

Start by understanding what the file contains and how the Android build uses it.

What google-services.json does

After registering an Android app in Firebase Console, you can download a google-services.json file for that app.

It contains configuration such as:

• Firebase project ID
• Google Cloud project number
• Firebase app ID
• Android package name
• API key used by Firebase services
• OAuth client information
• Storage bucket and related project settings

The Google Services Gradle Plugin reads the JSON and converts its values into Android resources used by Firebase SDKs.

google-services.json
↓
Google Services Gradle Plugin
↓
generates google_app_id, project_id, API-key resources, and more
↓
Firebase SDKs use the generated resources during initialization

It is not an administrator private key

google-services.json contains project-specific configuration, but it is not a Firebase administrator private key.

Hiding this file alone does not protect Firestore, Realtime Database, or Storage data.

Actual protection requires controls such as:

• Firebase Authentication
• Firestore Security Rules
• Realtime Database Rules
• Storage Security Rules
• Firebase App Check
• Appropriate API-key restrictions

Never add these values to the JSON file:

• Service-account private keys
• Secrets for external APIs
• Payment-provider secret keys
• Administrator tokens
• OAuth client secrets

Placement in a standard Android project

Place the file at the root of the app module.

project/
├── app/
│   ├── google-services.json
│   ├── build.gradle.kts
│   └── src/
├── build.gradle.kts
└── settings.gradle.kts

The normal path is:

app/google-services.json

It is not normally placed at the root of the entire project.

Incorrect examples

project/google-services.json

project/config/google-services.json

Leaving the file in the Downloads folder also does not make Gradle process it.

Placement in Flutter

The Android app module of a Flutter project is usually android/app/.

flutter_project/
├── android/
│   └── app/
│       ├── google-services.json
│       └── build.gradle.kts
├── lib/
└── pubspec.yaml

The normal path is:

android/app/google-services.json

Current FlutterFire setup commonly uses:

flutterfire configure

This usually creates or updates:

lib/firebase_options.dart

Confirm that the Android JSON and the Dart FirebaseOptions both point to the intended Firebase project.

Placement in React Native and Expo

In a bare React Native project, the Android app module is also commonly:

android/app/google-services.json

Expo or EAS Build can reference the file through an app-config field such as android.googleServicesFile.

Regardless of the workflow, verify that the correct file reaches the final generated Android app before the build runs.

Check the file name

Downloading the file repeatedly may cause the operating system to rename it.

google-services (1).json
google-services (2).json

The expected name is:

google-services.json

On Windows, hidden extensions can also produce names such as:

google-services.json.txt
google-services.json.json

Enable extension display and confirm the exact name.

Check the Android package name

The JSON contains the Android package registered in Firebase.

{
  "client": [
    {
      "client_info": {
        "android_client_info": {
          "package_name": "com.example.app"
        }
      }
    }
  ]
}

It must match the final Gradle applicationId.

android {
    defaultConfig {
        applicationId = "com.example.app"
    }
}

Check applicationId, not only namespace

android {
    namespace = "com.example.app.code"

    defaultConfig {
        applicationId = "com.example.app"
    }
}

Firebase normally uses the applicationId that identifies the installed and Play-distributed app.

Confirm the Firebase project connection

Open google-services.json in a text editor and check project_id.

{
  "project_info": {
    "project_id": "example-app-prod"
  }
}

Compare it with the unique project ID shown in Firebase Console. Do not rely only on the project’s display name.

Important fields

Do not identify the target project from the API key alone. Check both project_id and package_name.

Apply the Google Services Gradle Plugin

Placing the JSON file is not enough. Apply the Google Services Plugin to the app module.

Kotlin DSL

plugins {
    id("com.android.application")
    id("com.google.gms.google-services")
}

At the project level, declare the current plugin version specified by the official setup documentation.

plugins {
    id("com.google.gms.google-services") version "CURRENT_VERSION" apply false
}

After processing the JSON, the plugin creates generated resources under a path similar to:

app/build/generated/res/google-services/

The generated values.xml contains resources such as google_app_id and project_id.

Separate development and production environments

With product flavors, each environment can use its own configuration file.

app/
└── src/
    ├── development/
    │   └── google-services.json
    └── production/
        └── google-services.json

Example:

development
applicationId: com.example.app.dev
Firebase project: example-app-dev

production
applicationId: com.example.app
Firebase project: example-app-prod

For every environment, verify both the project_id and package_name, not only the file name.

When to download or regenerate the configuration

Get the latest file from Firebase Console, or rerun FlutterFire configuration, after changes such as:

• Registering another Android app in Firebase
• Adding a SHA-1 certificate for Google Sign-In
• Changing OAuth client configuration
• Switching to another Firebase project
• Adding a product flavor
• Changing API-key configuration
• Adding Firebase products or target platforms in Flutter

After Google Sign-In configuration changes, downloading the latest configuration can be necessary because OAuth client information may have changed.

Rebuild after replacing the file

Android

./gradlew clean
./gradlew assembleDebug

For an App Bundle:

./gradlew clean
./gradlew bundleRelease

Flutter

flutterfire configure
flutter clean
flutter pub get
flutter run

Increase versionCode when publishing an updated build to Google Play.

Common errors

File google-services.json is missing

Check:

• Whether the file exists
• Whether it is directly under the app module
• Whether the file name is exact
• Whether CI restored the file before the build
• Whether the selected build type or flavor has an appropriate file

No matching client found for package name

Check:

• The final Gradle applicationId
• The JSON package_name
• Any applicationIdSuffix
• The selected build variant
• Whether the file came from the correct Firebase Android app

Data is written to another project

Check:

• project_id
• Selected build variant
• Flavor-specific JSON placement
• Flutter’s firebase_options.dart
• The file restored by CI

Handling the file in CI

Some projects do not commit google-services.json and instead restore it before the build.

- name: Restore google-services.json
  run: |
    mkdir -p android/app
    echo "${{ secrets.GOOGLE_SERVICES_JSON_BASE64 }}" \
      | base64 --decode \
      > android/app/google-services.json

After restoration, verify that the file exists and that its project_id matches the intended environment.

Do not print the complete file contents in CI logs.

Common misunderstandings

Editing package_name makes the JSON reusable for another app

Do not manually change only package_name.

Firebase app ID, OAuth clients, API keys, and other values are linked. Register the correct Android app in Firebase and download its official configuration.

Replacing the JSON moves existing Firebase data

It does not.

It changes the project used by newly built app versions. Existing Firestore, Authentication, and Storage data must be migrated separately when necessary.

Hiding the API key protects Firebase data

Security Rules, Authentication, App Check, and appropriate API restrictions protect Firebase resources. Hiding the client configuration is not a substitute for access control.

Summary

For a reliable google-services.json setup:

1. Download it from the intended Firebase project
2. Place it in the correct app module
3. Use the exact file name
4. Match applicationId with package_name
5. Verify the destination with project_id
6. Apply the Google Services Gradle Plugin
7. Separate configuration by flavor when needed
8. Refresh configuration after OAuth or SHA changes
9. Keep Flutter FirebaseOptions aligned with the Android JSON
10. Perform a clean rebuild after replacement

For a missing-file error, see google-services.json Missing from the Module Root. For a package mismatch, see No Matching Client Found for Package Name.