How to fix INVALID_ARGUMENT: Composite index is required for this query in Firebase

FirebaseBEGINNERMEDIUMUpdated Dec 22, 2025· 129 views

Firestore throws this error when your query combines multiple filters or sorting without a pre-built composite index. Create the missing index via the Firebase Console link in the error message or use the Firebase CLI.

Quick fix

Fixes INVALID_ARGUMENT: Composite index is required for this query

When you encounter the error, check your browser console or Firebase SDK logs. The error message includes a direct link (usually starting with `https://console.firebase.google.com/...`). Click this link and the Firebase Console will automatically populate the index configuration based on your query.
  1. Follow the error link in Firebase Console
  2. Review and create the index
  3. Verify index status
  4. Alternative: Use Firebase CLI for batch index creation
firebase — error
When you encounter the error, check your browser console or Firebase SDK logs. The error message includes a direct link (usually starting with `https://console.firebase.google.com/...`). Click this link and the Firebase Console will automatically populate the index configuration based on your query.
INVALID_ARGUMENT: Composite index is required for this query

What this error means

This error occurs when you attempt a complex Firestore query that combines filtering (where clauses) with sorting (orderBy), but no composite index exists to support it. Firestore automatically creates single-field indexes, but composite indexes—which cover multiple fields—must be created manually because of the large number of possible field combinations. When Firestore encounters a query it cannot execute, it returns an error with a direct link to create the required index.

Typical symptoms

  • Queries combining multiple where clauses and orderBy fail with INVALID_ARGUMENT error
  • Error message includes a link to create the missing index in Firebase Console
  • App crashes or query execution is blocked when using complex filter+sort combinations
  • Error appears during testing or when new query patterns are used

Common causes

  1. Query uses range filtering (where with >, <, >=, <=) combined with orderBy on different fields without a composite index
  2. Multiple where clauses combined with orderBy require an index that covers all specified fields
  3. Composite index was not created before attempting the query
  4. Index creation is still in progress and not yet available for queries

How to fix "INVALID_ARGUMENT: Composite index is required for this query"

1Follow the error link in Firebase Console
javascript
When you encounter the error, check your browser console or Firebase SDK logs. The error message includes a direct link (usually starting with `https://console.firebase.google.com/...`). Click this link and the Firebase Console will automatically populate the index configuration based on your query.
2Review and create the index

In the Firebase Console, navigate to Firestore Database > Indexes > Composite. The index configuration should be pre-filled with your collection name and field definitions. Review the fields and their sort order (Ascending/Descending), then click Create Index. Building the index typically takes a few minutes depending on your data size.

3Verify index status

Wait for the index status to change from "Building" to "Enabled". You can monitor progress in the Composite Indexes tab. Once enabled, your query will execute successfully.

4Alternative: Use Firebase CLI for batch index creation

If you have multiple indexes to create, use the Firebase CLI:

bash
firebase init firestore

This generates a firestore.indexes.json file in your project. Edit it to define all your composite indexes:

json
{
  "indexes": [
    {
      "collectionGroup": "posts",
      "queryScope": "Collection",
      "fields": [
        { "fieldPath": "status", "order": "ASCENDING" },
        { "fieldPath": "createdAt", "order": "DESCENDING" }
      ]
    }
  ]
}

Then deploy:

bash
firebase deploy --only firestore:indexes
5Test your query

After the index is enabled, run your query again. It should now execute without the composite index error. If using the SDK, you do not need to change your code—Firestore will automatically use the new index.

Advanced notes

Index Planning: Firestore has a limit of 200 composite indexes per database. Plan your queries to reuse indexes where possible. For subcollections with the same name across different parent documents, Firestore can share a single index.

Index Merging: For queries with multiple equality (==) clauses, Firestore can sometimes merge existing single-field indexes. However, queries combining range filters (>, <, >=, <=) with orderBy on different fields always require a dedicated composite index.

Performance Consideration: Composite indexes improve query performance for complex searches but add write latency. Index creation is asynchronous and may take time on large collections. Plan index creation before deploying to production.

Frequently asked questions

What does "INVALID_ARGUMENT: Composite index is required for this query" mean?
This error occurs when you attempt a complex Firestore query that combines filtering (where clauses) with sorting (orderBy), but no composite index exists to support it. Firestore automatically creates single-field indexes, but composite indexes—which cover multiple fields—must be created manually because of the large number of possible field combinations. When Firestore encounters a query it cannot execute, it returns an error with a direct link to create the required index.
How do I fix "INVALID_ARGUMENT: Composite index is required for this query"?
Firestore throws this error when your query combines multiple filters or sorting without a pre-built composite index. Create the missing index via the Firebase Console link in the error message or use the Firebase CLI.
What causes "INVALID_ARGUMENT: Composite index is required for this query"?
Query uses range filtering (where with >, <, >=, <=) combined with orderBy on different fields without a composite index Multiple where clauses combined with orderBy require an index that covers all specified fields Composite index was not created before attempting the query
Is the "INVALID_ARGUMENT: Composite index is required for this query" error serious?
It is a medium-severity error — more of a blocker than a risk. The steps above resolve it.

Official resources & further reading