How to fix Error: Error creating Firestore Database: AlreadyExists in Terraform

TerraformINTERMEDIATEMEDIUMUpdated Dec 31, 2025· 143 views

This error occurs when Terraform attempts to create a Firestore database that already exists in your GCP project. The most common cause is that GCP automatically created a default Firestore database when you enabled related services. You can fix this by importing the existing database into Terraform state or using the existing database in your configuration.

Quick fix

Fixes AlreadyExists

# List all Firestore databases in your project
gcloud firestore databases list --project=MY_PROJECT_ID
  1. Import the existing Firestore database into Terraform state
  2. Add google_project_service to manage App Engine and Firestore dependencies
  3. Verify the existing database location and type
  4. Remove conflicting google_firestore_database resource temporarily
terraform — error
# List all Firestore databases in your project
gcloud firestore databases list --project=MY_PROJECT_ID
Error: Error creating Firestore Database: AlreadyExists

What this error means

When you deploy Firestore infrastructure using Terraform, the `google_firestore_database` resource attempts to create a new database instance. The "AlreadyExists" error means Terraform is trying to create a database with a name (usually "(default)") that already exists in your GCP project. This typically happens because: 1. **Google Cloud automatically provisioned a default database**: When you enable certain services (like Cloud Storage via `google_app_engine_application`), GCP automatically creates a default Firestore database instance as a side effect. 2. **Database was created outside of Terraform**: The database exists in GCP but not in your Terraform state file, causing Terraform to try creating a "new" one that already exists. 3. **State mismatch**: Your Terraform state file doesn't reflect the actual resources in GCP, causing a discrepancy. The error prevents your Terraform configuration from being applied because Terraform cannot create a resource that already exists in GCP.

Typical symptoms

  • Terraform apply fails with 'Error: Error creating Firestore Database: AlreadyExists'
  • Error occurs on the `google_firestore_database` resource
  • Database appears in GCP Console but not in Terraform state
  • Error message includes database name like '(default)'
  • Issue occurs when adding Firestore to an existing GCP project
  • Previous deployments created the database outside of Terraform

Common causes

  1. GCP automatically created a default Firestore database when enabling google_app_engine_application or other services
  2. Database was manually created in GCP Console before adding Terraform
  3. Terraform state file is out of sync with actual GCP resources
  4. Previous terraform apply was interrupted, leaving database in GCP but not recorded in state
  5. Multiple Terraform configurations trying to create the same database
  6. Switching to a different Terraform backend that doesn't have the resource in state

How to fix "Error: Error creating Firestore Database: AlreadyExists"

1Import the existing Firestore database into Terraform state

The most straightforward solution is to import the existing database into your Terraform state. This tells Terraform that it now manages the existing resource.

First, find your GCP project ID and determine the database name (usually "(default)" for the default database):

bash
# List all Firestore databases in your project
gcloud firestore databases list --project=MY_PROJECT_ID

Then, import the database into your Terraform state:

bash
terraform import google_firestore_database.default projects/MY_PROJECT_ID/databases/(default)

If you have a differently named database resource in your Terraform config, adjust accordingly:

bash
terraform import google_firestore_database.my_database projects/MY_PROJECT_ID/databases/my-database-name

After importing, verify the state was updated:

bash
terraform state show google_firestore_database.default

Now terraform plan and apply should work without trying to recreate the database.

2Add google_project_service to manage App Engine and Firestore dependencies

If the database was created as a side effect of enabling google_app_engine_application, explicitly manage the dependency order in Terraform:

hcl
resource "google_project_service" "firestore" {
  service            = "firestore.googleapis.com"
  disable_on_destroy = false
}

resource "google_app_engine_application" "app" {
  depends_on = [google_project_service.firestore]

  project    = var.gcp_project_id
  location_id = "us-central"
  database_type = "CLOUD_FIRESTORE"
}

# This may conflict, so import the existing database instead
# resource "google_firestore_database" "default" {
#   project = var.gcp_project_id
#   name = "(default)"
#   location_id = "us-central"
#   type = "FIRESTORE_NATIVE"
# }

By declaring google_project_service.firestore and using depends_on, you control when Firestore is enabled. However, App Engine may still auto-create the database, so importing (Step 1) is still the recommended approach.

3Verify the existing database location and type

Before importing, confirm the database exists and note its properties:

bash
# Get detailed information about the default database
gcloud firestore databases describe --database=(default) --project=MY_PROJECT_ID

This shows:
- Database name (usually "(default)")
- Location (e.g., "us-central1")
- Type (e.g., "FIRESTORE_NATIVE" or "DATASTORE_MODE")
- Current status

Example output:

bash
name: projects/my-project/databases/(default)
location: us-central1
type: FIRESTORE_NATIVE
createTime: '2023-01-15T10:30:00Z'

Make sure your Terraform configuration matches these settings when you import the database.

4Remove conflicting google_firestore_database resource temporarily

If you have a google_firestore_database resource block in your Terraform configuration that conflicts with the existing database, you have two options:

Option A: Comment it out temporarily (for import)

hcl
# resource "google_firestore_database" "default" {
#   project = var.gcp_project_id
#   name = "(default)"
#   location_id = "us-central"
#   type = "FIRESTORE_NATIVE"
# }

Run terraform import (Step 1), then uncomment it. The import command creates a matching state entry so the resource declaration matches the state.

Option B: Delete and recreate (advanced)

If you're in development and can afford downtime:

bash
# Delete the database in GCP
gcloud firestore databases delete --database=(default) --project=MY_PROJECT_ID

# Now terraform apply will create it fresh
terraform apply

Warning: Deleting a Firestore database is irreversible and deletes all data. Only use this in development environments.

5Use data source to reference existing database

If you prefer not to manage the Firestore database with Terraform, use a data source to reference the existing database:

hcl
# Reference the existing database without managing it
data "google_firestore_database" "default" {
  project  = var.gcp_project_id
  database = "(default)"
}

output "firestore_database" {
  value = data.google_firestore_database.default
}

This approach:
- Reads the database properties from GCP
- Does NOT try to create or modify the database
- Allows you to reference it in other resources (e.g., indexes, security rules)
- Is useful when the database lifecycle is managed outside of Terraform

This is ideal if the database is shared across multiple Terraform configurations or managed by a different team.

6Fix the dependency order between google_app_engine_application and google_firestore_database

If you're using both google_app_engine_application and google_firestore_database, the order matters:

hcl
resource "google_project_service" "appengine" {
  service            = "appengine.googleapis.com"
  disable_on_destroy = false
}

resource "google_project_service" "firestore" {
  service            = "firestore.googleapis.com"
  disable_on_destroy = false
}

resource "google_app_engine_application" "app" {
  depends_on = [
    google_project_service.appengine,
    google_project_service.firestore,
  ]

  project      = var.gcp_project_id
  location_id  = "us-central"
  database_type = "CLOUD_FIRESTORE"
}

# Import existing database instead of creating
# Or use data source (see Step 5)

Important note: Even with proper depends_on, the App Engine application may auto-create the Firestore database as a side effect. The import approach (Step 1) is the most reliable fix.

Advanced notes

### Understanding GCP Auto-Provisioning

When you create a google_app_engine_application resource with database_type = "CLOUD_FIRESTORE", Google Cloud automatically provisions a default Firestore database. This happens asynchronously and is not directly tracked by Terraform. If you then try to create a google_firestore_database resource for the same database, it fails because the database already exists.

This is a known limitation documented in the Terraform Google Provider GitHub issues (see sources).

### Database Location Locking

Once you create a Firestore database in a specific location (e.g., "us-central1"), you cannot change the location. The location is set at database creation time and is permanent. This is why it's critical to import the database with the correct configuration that matches the existing database in GCP.

### Datastore Mode vs Firestore Native

GCP supports two Firestore modes:

- FIRESTORE_NATIVE: Modern Firestore with Firebase SDKs, real-time listeners, and Firebase Security Rules
- DATASTORE_MODE: Legacy Datastore mode, not compatible with Firebase SDKs

When imported, the database will have the mode it was created with. Make sure your Terraform configuration matches the existing mode.

### Multi-Database Firestore (Advanced)

Firestore now supports multiple databases in a single project (in addition to the default database). If you're using named databases:

bash
terraform import google_firestore_database.named_db projects/MY_PROJECT_ID/databases/my-custom-database

This allows you to have a default database (auto-provisioned) and custom databases (managed by Terraform).

### State File Considerations

After importing, ensure your Terraform state file is properly stored and backed up:

hcl
terraform {
  backend "gcs" {
    bucket  = "my-terraform-state"
    prefix  = "firestore"
  }
}

Never lose your state file, as it tracks which GCP resources Terraform manages. If the state is lost, you'll encounter "AlreadyExists" errors again.

Frequently asked questions

What does "AlreadyExists" mean?
When you deploy Firestore infrastructure using Terraform, the google_firestore_database resource attempts to create a new database instance. The "AlreadyExists" error means Terraform is trying to create a database with a name (usually "(default)") that already exists in your GCP project. This typically happens because: 1.
How do I fix "AlreadyExists"?
This error occurs when Terraform attempts to create a Firestore database that already exists in your GCP project. The most common cause is that GCP automatically created a default Firestore database when you enabled related services. You can fix this by importing the existing database into Terraform state or using the existing database in your configuration.
What causes "AlreadyExists"?
GCP automatically created a default Firestore database when enabling google_app_engine_application or other services Database was manually created in GCP Console before adding Terraform Terraform state file is out of sync with actual GCP resources
Is the "AlreadyExists" error serious?
It is a medium-severity error — more of a blocker than a risk. The steps above resolve it.

Official resources & further reading