apache/cassandra · error · InvalidRequestException

It's not possible to use all the specified included indexes

Error message

It's not possible to use all the specified included indexes with this query.

What it means

InvalidRequestException thrown by IndexHints.validate when index hints specify included indexes but there is no query plan, or the request cannot be checked against one. Without a plan there is no way to prove the included indexes are usable, so Cassandra rejects the request up front.

Source

Thrown at src/java/org/apache/cassandra/db/filter/IndexHints.java:320

        return new IndexHints(included, excluded);
    }

    /**
     * Validates these index hints for the specified index query plan, to verify that all the included indexes can be
     * selected. This might happen if the query doesn't have expressions for each of the included indexes, or if it has
     * them but the index implementation hasn't been able to use them for whatever reason.
     *
     * @param queryPlan the index query plan, which should have been built accordingly to these hints
     */
    public void validate(@Nullable Index.QueryPlan queryPlan)
    {
        if (queryPlan == null)
        {
            if (included.isEmpty())
                return;
            else
                throw new InvalidRequestException(NON_INCLUDABLE_INDEXES_ERROR);
        }

        for (IndexMetadata indexMetadata : included)
        {
            boolean found = false;
            for (Index i : queryPlan.getIndexes())
            {
                if (i.getIndexMetadata().equals(indexMetadata))
                {
                    found = true;
                    break;
                }
            }
            if (!found)
                throw new InvalidRequestException(NON_INCLUDABLE_INDEXES_ERROR);
        }

        // excluded indexes should never be included because the query plans are built from a filtered list

View on GitHub (pinned to 88fd0f6a0e)

Solutions

Remove the included index hints from the query
Ensure the query is one that goes through index planning (has a query plan)
Verify the hinted indexes exist on the table and are queryable

Example fix

// before
SELECT * FROM t WHERE a = 1; -- client attaches INCLUDE INDEXES with no query plan
// after
SELECT * FROM t WHERE a = 1 AND expr(t_index, 'a eq 1'); -- use a plan-backed indexed query

Defensive patterns

Strategy: validation

Validate before calling

if (hints != null && hints.included != null && queryPlan == null) throw new IllegalArgumentException("Included index hints require a query plan");

Try / catch

try { session.execute(stmt); } catch (InvalidRequestException e) { if (e.getMessage().contains("included indexes")) stmt = stripIndexHints(stmt); }

Prevention

Attach included hints only to queries that go through index planning
Validate hints client-side against the table's existing indexes
Strip hints in fallback paths that bypass planning

When it happens

Trigger: Executing a SELECT with INCLUDE INDEXES hints on a query that produced a null query plan in validate(), or hints supplied where index selection never runs.

Common situations: Client drivers or prepared-statement paths attaching included-index hints to queries that bypass index planning; queries against tables where hints are meaningless.

Understand the failure class

Background: "Invalid query parameter" / "Failed to parse value of ...": fixing bad query string parameters across APIs — this error's family across 36 libraries.

Related errors

AI-assisted analysis of apache/cassandra@88fd0f6a0e (2026-09-10). Data as JSON: /api/errors/8ddc77f608ae6e39. Report an issue: GitHub.