## TL;DR

Firestore needs a composite index for any query that combines a range filter with ordering or filtering on another field, and the error message already tells you exactly which index to build: its console link pre-fills the collection, fields, and sort directions. Open the link and create the index, or declare it in firestore.indexes.json and deploy. Then wait for the build to finish before retrying; a building index does not serve queries yet.

```text
FAILED_PRECONDITION: The query requires an index. You can create it here: https://console.firebase.google.com/.../firestore/indexes?create_composite=...
```

## Steps

1. Copy the console link from the error message and open it. It pre-fills the collection id, the fields, and each field's sort direction.
   Expected: the console shows the exact composite index definition your query needs. No guessing.

2. Create the index in the console, or add the matching entry to firestore.indexes.json under compositeIndexes and deploy with firebase deploy limited to firestore indexes.
   Expected: the index appears with status building.

3. Wait for the build to complete. Watch the status in the console; large collections can take a while.
   Expected: status flips to enabled. Only then does the index serve queries.

4. Retry the query.
   Expected: results return with no FAILED_PRECONDITION error.

5. Prevent repeats: list every compound query your app runs (range filter plus sort or second filter) and define their indexes in firestore.indexes.json in version control.
   Expected: deploys create the indexes before the code that needs them ships.

## Use this when

- A Firestore query fails with FAILED_PRECONDITION and an index-required message.
- The query has a range filter on one field plus ordering or a filter on another.
- Simple single-field queries work but the compound one fails.
- The error includes a console link to create the index.

## Not for this skill when

- The query fails with permission-denied. That is a security-rules problem, not an index problem.
- The index exists and is enabled but the query still fails. Check that the query matches the index definition exactly, field order and directions included.
- You are using the emulator. The emulator does not enforce composite indexes the same way; test index needs against the real project.

## Variant phrasings

- firestore the query requires an index
- firestore FAILED_PRECONDITION index required compound query
- firestore composite index which fields
- firebase firestore.indexes.json compositeIndexes example
- firestore orderBy where index required

## Why it happens

Firestore executes queries by walking prebuilt indexes, not by scanning documents. Single-field queries use automatic single-field indexes, but a query that filters a range on one field and orders or filters on another needs a composite index that stores the fields together in the right order. Without it, Firestore cannot execute the query at all, so it fails fast with the exact definition of the missing index instead of running slowly.

## Edge cases

- Field order and sort direction in the index must match the query. An index on (status ASC, createdAt DESC) does not serve a query sorting (status DESC, createdAt ASC).
- Array-contains combined with ordering needs its own composite index too. It is easy to miss because the filter looks single-field.
- Index builds on huge collections take time and the query keeps failing until the build finishes. Do not redeploy or recreate the index while it builds.
- The free tier limits composite index counts per project. If you are near the cap, consolidate queries onto shared indexes where the field prefixes match.

## Provenance

Resolved from the public thread: https://vectle.com/posts/pst_KktNu9YxYp7G83_dGn-fzw