Firestore 'The Query Requires an Index' in Flutter? 5 Query Shapes and How to Fix Each (2026)

By · Published 2026-11-17 · Last verified 2026-11-17

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.

Grid of the five Firestore query shapes that need a composite index in Flutter: equality plus sort, range plus sort, arrayContains plus sort, two range filters and a collection group query, with the fix of creating the index and waiting for it to build
Five query shapes that need an index.

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 DartExampleIndex you need
1Equality on one field, orderBy on anotherwhere('uid', isEqualTo: u).orderBy('createdAt', descending: true)uid ascending, createdAt descending
2Range filter on one field, sort on anotherwhere('price', isLessThan: 50).orderBy('rating')Composite on both fields
3arrayContains plus a sort or another filterwhere('members', arrayContains: u).orderBy('lastMessageAt')members array-contains, lastMessageAt
4Range or inequality filters on two fieldswhere('age', isGreaterThan: 18).where('score', isGreaterThan: 10)Composite on both fields
5A collectionGroup querycollectionGroup('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:

StreamBuilder<QuerySnapshot>(
  stream: query.snapshots(),
  builder: (context, snapshot) {
    if (snapshot.hasError) {
      debugPrint('Firestore: ${snapshot.error}');
      return const Text('Could not load items');
    }
    // ...
  },
)
Two columns comparing creating a Firestore index from the link in the error, which opens the Firebase console with fields pre-filled for one project, with keeping it in firestore.indexes.json and deploying it with the Firebase CLI
Error link or indexes file.

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.

Four boxes of checks when the index error continues: the index is Enabled not Building, fields and sort order match, the scope matches, and it is on the database the app uses
Four checks if the error continues.

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:

  1. Status: the index shows as Enabled, not Building.
  2. Fields and order: the same fields, in the same order, with the same sort direction as the Dart query.
  3. Scope: Collection for collection(), Collection group for collectionGroup().
  4. Database: the index is on the database the app uses, if your project has more than one Firestore database.
  5. New error, new index: changing a filter, adding a limit with 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 billing200
Composite indexes per database, billing enabled1,000
Fields in one composite index100
Index entries per document40,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.

Vertical Pinterest graphic with five fixes for the Firestore error the query requires an index in Flutter
Pinterest pin: Firestore query requires an index.

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