apache/cassandra · error · InvalidRequestException

Cannot have more than 'secondary_indexes_per_table_fail_thre

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.

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)

Solutions

  1. Reduce the number of included indexes in the query to the essential ones
  2. Raise the secondary_indexes_per_table_fail_threshold setting if the workload genuinely needs more
  3. 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

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.