Diagnosing Firestore Query Failures from Missing Composite Indexes and Invalid Query Shapes

Firestore queries with multiple filters, orderBy, or collectionGroup either fail immediately with FAILED_PRECONDITION and an index creation link, or succeed with p95 latency spikes and read throttling in metrics. The useful takeaway is that the error is almost always a shape mismatch, not a missing single-field index, and the fix is tied to the exact field order in the query.

Recognizable condition

A query that worked in development fails in production, or latency degrades after adding a sort. Client SDKs do not validate shape locally. The server returns FAILED_PRECONDITION with the message The query requires an index and a console link. Alternatively, the query runs but Cloud Monitoring shows rising query latency and throttled read operations while document read count stays flat.

Composite index means a server-side index on a combination of fields with a specific order. Firestore automatically maintains single-field indexes. Composite indexes must be created explicitly for queries that combine where filters with orderBy or use collectionGroup.

Cause diagnostic table

Ordered checks

1. Reproduce the exact query. Run the same query in Firestore Emulator or Firestore Console with the same parameters. Capture the error code and the index creation URL from the error. Do this in a non-prod project. Required permission: Firestore Viewer on the project.

2. Inspect query shape. List the where clauses and orderBy clauses. Note which fields use <, >, <=, >= or !=. If more than one field uses an inequality, the shape is invalid regardless of indexes.

3. Check index state. Open Firebase Console > Firestore Database > Indexes. Filter by Collection. Check state Pending, Building, Ready and build time. A composite index that matches the query fields in the same order is required.

4. Export index definitions. Run locally with Firebase CLI installed:

   firebase firestore:indexes list --project <project-id>

   Required permission: Firestore Index Admin. Compare the output fields and order with the query shape. Do not assume the UI name matches the query.

Fixes tied to findings

Missing composite index

Use the link from the error to create the suggested composite index. Wait until state is Ready. Index creation is automatic but costs storage and increases write overhead per document. Avoid creating many ad-hoc indexes without cleanup.

Verification: Console shows Ready and the field order matches the query. Re-run the query in Emulator with logging enabled to confirm the error code disappears.

Multiple inequality filters

Refactor to use a single inequality field. Move additional filters to client-side filtering or split into two queries and merge results client-side. This is a server-enforced constraint; no index will fix it.

orderBy order mismatch

Add orderBy on the inequality field first, then secondary sorts. Example shape: where('createdAt', '>=', start).orderBy('createdAt').orderBy('priority', 'desc'). If the query requires a different order, create a composite index with that exact order.

Collection group query

Create a collectionGroup composite index. The index scope must be collectionGroup and include the collection name. The console link will prefill this.

Escalation criteria

• Index build remains Pending longer than 60-90 minutes for a small collection. Large collections take longer. Check collection size and ongoing writes.
• Query still fails after index shows Ready. Re-check field order and data types. A type mismatch on a field prevents index use.
• Repeated PERMISSION_DENIED or RESOURCE_EXHAUSTED. This suggests security rules get() loops or hot spots, not an index issue.
• Latency remains high after index fix. Review data model for fan-out writes and consider denormalization. Hot spot throttling can mimic index issues.

Limitations and verification

Composite index names and UI paths are version-sensitive across Firebase Console releases. Query shape constraints are enforced server side; client SDKs will not warn until runtime, so test queries in non-prod first.

Practical checks after fix:

• Open Firebase Console > Firestore Database > Indexes and confirm the composite index exists with state Ready and matches query fields order.
• Check Cloud Monitoring Firestore metrics for read ops, document read count, and query latency before and after the fix.

Rollback is not required for index creation, but you can delete unused composite indexes via Console or CLI to reduce storage and write cost.