🚨 GCP Error: 'The query requires an index' — Cause, Fix, and Troubleshooting Guide

Overview

Firestore rejects queries that need a composite index that doesn’t exist yet. Simple single-field queries are auto-indexed, but a query that combines multiple fields (e.g. an equality filter plus an ordering, or multiple range/inequality filters) requires an explicit composite index:

FAILED_PRECONDITION: The query requires an index. You can create it here:
https://console.firebase.google.com/project/acme-prod-platform/firestore/indexes?create_composite=Cl...

The error is a FAILED_PRECONDITION (HTTP 400) — the data and permissions are fine; the index that makes the query servable is missing.

Symptoms

• Queries fail with FAILED_PRECONDITION: The query requires an index and a create_composite=... link.
• A query works in one environment (indexes deployed) but fails in another (indexes not deployed).
• The failure appears only for multi-field queries; single-field ones succeed.
• Client libraries surface it as FailedPrecondition / gRPC code 9.

Common Root Causes

1. A new composite query with no matching index

You added an ordering or a second filter field and never created the composite index it needs.

2. Indexes not deployed to this project/database

firestore.indexes.json exists in source but was never firebase deploy-ed to the target project.

3. Index still building

The index was created but is still in the CREATING state; queries fail until it is READY.

4. Query shape doesn’t match any existing index

Field order, sort direction, or an added array-contains differs from the index definition.

How to Diagnose

All read-only.

# List existing composite indexes and their state
gcloud firestore indexes composite list \
  --project=acme-prod-platform \
  --format="table(name.basename(), state, fields[].fieldPath)"

# Confirm the active database/project
gcloud config get-value project

# In source control, check the tracked index definitions
cat firestore.indexes.json | grep -A6 '"collectionGroup"'

Compare the failing query’s fields/sort order against the listed indexes. A state: CREATING row means you just need to wait.

Fixes

Fastest: click the console link in the error. It pre-fills the exact composite index; create it and wait for READY.

Reproducible: define and deploy the index as code. Add it to firestore.indexes.json:

{
  "indexes": [
    {
      "collectionGroup": "orders",
      "queryScope": "COLLECTION",
      "fields": [
        { "fieldPath": "customerId", "order": "ASCENDING" },
        { "fieldPath": "createdAt", "order": "DESCENDING" }
      ]
    }
  ]
}

firebase deploy --only firestore:indexes --project acme-prod-platform

Wait for the build. Large collections take minutes to hours; poll until state is READY:

gcloud firestore indexes composite list --project=acme-prod-platform \
  --format="value(name.basename(), state)"

What to Watch Out For

• Never rely on the console click-through as your only source of truth — commit indexes to firestore.indexes.json so every environment gets them.
• Index build time scales with existing document count; deploy indexes before the query ships to avoid production failures.
• The index field order and sort directions must match the query exactly; reversing a sort needs a different (or additional) index.
• This is not a permissions error — do not touch Firestore Security Rules or IAM for a FAILED_PRECONDITION index message.

Related

• GCP Error: ‘INVALID_ARGUMENT’
• GCP Error: ‘The resource … was not found’ (404)
• GCP Error: ‘DEADLINE_EXCEEDED’
• More in the GCP error guides.