Firestore 'The Query Requires an Index' in Flutter? 5 Query Shapes and How to Fix Each (2026)
Why does Flutter say "The query requires an index"?
Because your Firestore query combines fields in a way that no existing index covers, so Firestore refuses to run it and returns [cloud_firestore/failed-precondition] The query requires an index. Firebase's documentation says Cloud Firestore requires an index for every query, creates the indexes for basic queries automatically, and returns an error with a direct link to create the missing one when a compound query doesn't map to an existing index. The fix is almost always to create that composite index, then wait for it to finish building. This guide shows the five query shapes that trigger it, three ways to create the index and how to keep indexes in your repo. Checked against the Firebase docs on 2026-11-17.
Which Flutter queries need a composite index?
Any query that filters or sorts on more than one field, with a few exceptions for pure equality filters. Firestore builds single-field indexes for you, so where('status', isEqualTo: 'open') or orderBy('createdAt') alone work out of the box. These five shapes are the usual triggers:
| # | Query shape in Dart | Example | Index you need |
|---|---|---|---|
| 1 | Equality on one field, orderBy on another | where('uid', isEqualTo: u).orderBy('createdAt', descending: true) | uid ascending, createdAt descending |
| 2 | Range filter on one field, sort on another | where('price', isLessThan: 50).orderBy('rating') | Composite on both fields |
| 3 | arrayContains plus a sort or another filter | where('members', arrayContains: u).orderBy('lastMessageAt') | members array-contains, lastMessageAt |
| 4 | Range or inequality filters on two fields | where('age', isGreaterThan: 18).where('score', isGreaterThan: 10) | Composite on both fields |
| 5 | A collectionGroup query | collectionGroup('comments').where('authorId', isEqualTo: u) | A collection group scope index |
Shape 5 surprises people because it can fail with a single filter. Firebase's index overview states that automatic indexes with collection group scope are not maintained by default, so a query across every comments subcollection needs an index with collection group scope, created as an exemption or as a composite index.
Fix 1: open the link in the error message
Copy the URL from the error and open it while signed in to the Firebase console; it pre-fills the collection, fields and sort directions, so you only review and click Create. In a Flutter app the link appears in the debug console, for example E/flutter: Unhandled Exception: [cloud_firestore/failed-precondition] The query requires an index. You can create it here: https://console.firebase.google.com/.... If you listen with snapshots(), the same message arrives through the stream's error callback.
Two things trip people up:
- The link opens the wrong project. The URL contains the project ID the app is connected to. If you have separate staging and production projects, the link only fixes the one that threw. Our guide to separate staging and production Firebase projects explains why each project needs its own setup.
- The error is swallowed. A
StreamBuilderthat never readssnapshot.hasErrorjust shows an empty list. Print the error once during development so you can see the link.
StreamBuilder<QuerySnapshot>(
stream: query.snapshots(),
builder: (context, snapshot) {
if (snapshot.hasError) {
debugPrint('Firestore: ${snapshot.error}');
return const Text('Could not load items');
}
// ...
},
)
Fix 2: add the index by hand in the Firebase console
Go to Firestore in the Firebase console, open the Indexes tab, click Add Index, enter the collection and the fields in the same order as your query, then click Create. Firebase's index guide notes that for non-array and non-map fields you must pick ascending or descending even when the field is only used for equality, and that the choice doesn't change how equality filters behave.
Match the order of the query: equality fields first, then the field you sort or range-filter on, with the same direction as your orderBy. A query that sorts createdAt descending needs a descending index on that field; an ascending one won't serve it.
Fix 3: keep indexes in firestore.indexes.json and deploy them
Run firebase init firestore once, add each index to the generated firestore.indexes.json, then deploy with firebase deploy --only firestore:indexes --project your-project-id. Firebase's documentation describes the CLI route and warns that if you edit indexes in the console, you should also update your local indexes file. Keeping the file in Git means a fresh project, a staging copy or a teammate's emulator gets the same indexes.
{
"indexes": [
{
"collectionGroup": "orders",
"queryScope": "COLLECTION",
"fields": [
{ "fieldPath": "uid", "order": "ASCENDING" },
{ "fieldPath": "createdAt", "order": "DESCENDING" }
]
}
],
"fieldOverrides": []
}
Our Flutter Firebase release checklist lists deploying indexes and rules before each release, so a new query never ships without its index.
Why does the error continue after I created the index?
Usually because the index is still building, or because the one you made doesn't match the query exactly. Firebase says indexes can take a few minutes to build depending on the amount of data, and the console shows a building status until they are ready. Check these in order:
- Status: the index shows as Enabled, not Building.
- Fields and order: the same fields, in the same order, with the same sort direction as the Dart query.
- Scope: Collection for
collection(), Collection group forcollectionGroup(). - Database: the index is on the database the app uses, if your project has more than one Firestore database.
- New error, new index: changing a filter, adding a
limitwith a new sort or switching direction can need another index; follow the new link.
If the error turns into a permissions error once the index exists, the index was the first problem and your rules are the next; see Firestore permission denied in Flutter.
Are there limits on how many indexes you can create?
Yes. The Firestore usage and limits page lists a maximum of 200 composite indexes per database when billing is not enabled, and 1,000 when billing is enabled, with up to 100 fields in one composite index and 40,000 index entries per document. A small Flutter app rarely gets near these, but generated queries, such as a filter screen that sorts by any column, can multiply indexes quickly.
| Limit (Firestore docs) | Value |
|---|---|
| Composite indexes per database, no billing | 200 |
| Composite indexes per database, billing enabled | 1,000 |
| Fields in one composite index | 100 |
| Index entries per document | 40,000 |
Each index also costs storage and write work, which is one more reason to remove indexes no query uses. If your read bill is the bigger worry, our guide to why Firestore reads are too high in a Flutter app covers the query side.
How do you avoid this error before release?
Run every screen's queries against a real Firebase project during testing and commit the indexes file with the code that needs it. Release builds behave the same as debug for Firestore indexes, but a query that only runs on a rarely used screen, such as an admin filter, may never have been exercised. Our guide to apps that work in debug but not release covers other gaps that testing misses.
We use this routine on the Flutter and Firebase apps we build at GSPTeck; see GSPTeck's apps and services for what we ship.
FAQ
Can a Flutter app create a Firestore index from code?
No. Client SDKs can't create indexes. Use the link in the error, the Firebase console, the Firebase CLI with firestore.indexes.json, the gcloud CLI or Terraform.
Does a simple orderBy need a composite index?
Not on its own. Firestore creates single-field indexes automatically, so ordering or filtering on one field works. You need a composite index when you combine fields, or a collection group scope index for collection group queries.
How long does a Firestore index take to build?
Firebase says a few minutes, depending on the size of the data. The console shows a building status until the index is enabled, and the query keeps failing until then.
Should I commit firestore.indexes.json to Git?
Yes. It lets you deploy the same indexes to every project and review index changes with the code that needs them. Update it whenever you add an index in the console.
Sources
- Firebase: Manage indexes in Cloud Firestore (checked 2026-11-17)
- Firebase: Index types in Cloud Firestore (last updated 2026-11-12; checked 2026-11-17)
- Firebase: Cloud Firestore usage and limits (checked 2026-11-17)