apache/cassandra · error · InvalidRequestException

Cannot have more than…

Error message

Cannot have more than 'secondary_indexes_per_table_fail_threshold' included/excluded indexes, found

What it means

InvalidRequestException from IndexHints.fromCQLNames when the set of included index names exceeds the secondary_indexes_per_table_fail_threshold limit. Cassandra caps how many index hints may be attached to a query to bound planning cost.

Solutions

Reduce the number of included indexes in the query to the essential ones
Raise the secondary_indexes_per_table_fail_threshold setting if the workload genuinely needs more
Drop redundant indexes and hints entirely

Example fix

// before
SELECT * FROM t WHERE ... ; -- INCLUDE INDEXES (i1, i2, ..., i20)
// after
SELECT * FROM t WHERE ... ; -- INCLUDE INDEXES (i1) -- only the index actually needed

Defensive patterns

Strategy: validation

Validate before calling

if (includedIndexes.size() > maxThreshold) throw new IllegalArgumentException("Too many included indexes: " + includedIndexes.size());

Try / catch

try { session.execute(stmt); } catch (InvalidRequestException e) { if (e.getMessage().contains("secondary_indexes_per_table_fail_threshold")) reduceHintsAndRetry(); }

Prevention

Keep hint lists small — only indexes the planner actually needs
Check the configured fail threshold before generating bulk hints
Avoid auto-hinting every index on the table

When it happens

Trigger: A CQL SELECT with an INCLUDED INDEXES list longer than the configured fail threshold, resolved in fromCQLNames before indexes are fetched.

Common situations: Auto-generated queries hinting dozens of indexes, misconfigured or too-low threshold in cassandra.yaml, bulk tooling copying hints across queries.

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/9059198ba3523303. Report an issue: GitHub.

Appendix: source

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

     * {@link InvalidRequestException} will be thrown.
     * </p>
     * All the mentioned indexes should exist in the index registry of the queried table,
     * or an {@link InvalidRequestException} will be thrown.
     *
     * @param included the names of the indexes to include when executing the query
     * @param excluded the names of the indexes to exclude when executing the query
     * @param table the queried table
     * @param indexRegistry the index registry of the queried table
     * @return the index hints represented by the specified sets of CQL names
     * @throws InvalidRequestException if any of the specified indexes do not exist in the specified index registry
     */
    public static IndexHints fromCQLNames(Set<QualifiedName> included,
                                          Set<QualifiedName> excluded,
                                          TableMetadata table,
                                          IndexRegistry indexRegistry)
    {
        if (included != null && included.size() > maxIncludedOrExcludedIndexCount())
            throw new InvalidRequestException(TOO_MANY_INDEXES_ERROR + included.size());

        if (excluded != null && excluded.size() > maxIncludedOrExcludedIndexCount())
            throw new InvalidRequestException(TOO_MANY_INDEXES_ERROR + excluded.size());

        IndexHints hints = IndexHints.create(fetchIndexes(included, table, indexRegistry),
                                             fetchIndexes(excluded, table, indexRegistry));

        if (hints == IndexHints.NONE)
            return hints;

        // Ensure that no index is both included and excluded
        Set<IndexMetadata> conflictingIndexes = Sets.intersection(hints.included, hints.excluded);
        if (!conflictingIndexes.isEmpty())
        {
            throw new InvalidRequestException(CONFLICTING_INDEXES_ERROR + IndexMetadata.joinNames(conflictingIndexes));
        }

        // Ensure that all nodes in the cluster are in a version that supports index hints, including this one

View on GitHub (pinned to 88fd0f6a0e)